From 475feb064bb6b9dfd34fc52762e3e0ab825254ec Mon Sep 17 00:00:00 2001 From: Magnus Ihse Bursie Date: Mon, 18 Nov 2024 09:23:50 +0000 Subject: [PATCH] 8344056: Use markdown format for man pages Reviewed-by: cstein, iris, dholmes --- make/common/modules/LauncherCommon.gmk | 10 - src/java.base/share/man/java.1 | 5409 ----------------- src/java.base/share/man/java.md | 4050 ++++++++++++ src/java.base/share/man/keytool.1 | 2991 --------- src/java.base/share/man/keytool.md | 2430 ++++++++ src/java.rmi/share/man/rmiregistry.1 | 100 - src/java.rmi/share/man/rmiregistry.md | 86 + src/java.scripting/share/man/jrunscript.1 | 166 - src/java.scripting/share/man/jrunscript.md | 141 + src/java.security.jgss/windows/man/kinit.md | 154 + src/java.security.jgss/windows/man/klist.md | 98 + src/java.security.jgss/windows/man/ktab.md | 134 + .../windows/man/jabswitch.md | 75 + .../windows/man/jaccessinspector.md | 249 + .../windows/man/jaccesswalker.md | 71 + src/jdk.compiler/share/man/javac.1 | 2372 -------- src/jdk.compiler/share/man/javac.md | 1952 ++++++ src/jdk.compiler/share/man/serialver.1 | 90 - src/jdk.compiler/share/man/serialver.md | 74 + src/jdk.hotspot.agent/share/man/jhsdb.1 | 218 - src/jdk.hotspot.agent/share/man/jhsdb.md | 186 + src/jdk.httpserver/share/man/jwebserver.1 | 193 - src/jdk.httpserver/share/man/jwebserver.md | 152 + src/jdk.jartool/share/man/jar.1 | 379 -- src/jdk.jartool/share/man/jar.md | 313 + src/jdk.jartool/share/man/jarsigner.1 | 1395 ----- src/jdk.jartool/share/man/jarsigner.md | 1089 ++++ src/jdk.javadoc/share/man/javadoc.1 | 1526 ----- src/jdk.javadoc/share/man/javadoc.md | 1214 ++++ src/jdk.jcmd/share/man/jcmd.1 | 1345 ---- src/jdk.jcmd/share/man/jcmd.md | 1032 ++++ src/jdk.jcmd/share/man/jinfo.1 | 103 - src/jdk.jcmd/share/man/jinfo.md | 88 + src/jdk.jcmd/share/man/jmap.1 | 106 - src/jdk.jcmd/share/man/jmap.md | 89 + src/jdk.jcmd/share/man/jps.1 | 235 - src/jdk.jcmd/share/man/jps.md | 189 + src/jdk.jcmd/share/man/jstack.1 | 89 - src/jdk.jcmd/share/man/jstack.md | 73 + src/jdk.jcmd/share/man/jstat.1 | 689 --- src/jdk.jcmd/share/man/jstat.md | 588 ++ src/jdk.jconsole/share/man/jconsole.1 | 104 - src/jdk.jconsole/share/man/jconsole.md | 86 + src/jdk.jdeps/share/man/javap.1 | 259 - src/jdk.jdeps/share/man/javap.md | 227 + src/jdk.jdeps/share/man/jdeprscan.1 | 271 - src/jdk.jdeps/share/man/jdeprscan.md | 217 + src/jdk.jdeps/share/man/jdeps.1 | 338 - src/jdk.jdeps/share/man/jdeps.md | 297 + src/jdk.jdeps/share/man/jnativescan.1 | 220 - src/jdk.jdeps/share/man/jnativescan.md | 175 + src/jdk.jdi/share/man/jdb.1 | 277 - src/jdk.jdi/share/man/jdb.md | 237 + src/jdk.jfr/share/man/jfr.1 | 438 -- src/jdk.jfr/share/man/jfr.md | 399 ++ src/jdk.jlink/share/man/jlink.1 | 409 -- src/jdk.jlink/share/man/jlink.md | 347 ++ src/jdk.jlink/share/man/jmod.1 | 423 -- src/jdk.jlink/share/man/jmod.md | 348 ++ src/jdk.jpackage/share/man/jpackage.1 | 834 --- src/jdk.jpackage/share/man/jpackage.md | 791 +++ src/jdk.jshell/share/man/jshell.1 | 1292 ---- src/jdk.jshell/share/man/jshell.md | 1042 ++++ src/jdk.jstatd/share/man/jstatd.1 | 219 - src/jdk.jstatd/share/man/jstatd.md | 180 + .../jdk/javadoc/tool/CheckManPageOptions.java | 23 +- 66 files changed, 18886 insertions(+), 22510 deletions(-) delete mode 100644 src/java.base/share/man/java.1 create mode 100644 src/java.base/share/man/java.md delete mode 100644 src/java.base/share/man/keytool.1 create mode 100644 src/java.base/share/man/keytool.md delete mode 100644 src/java.rmi/share/man/rmiregistry.1 create mode 100644 src/java.rmi/share/man/rmiregistry.md delete mode 100644 src/java.scripting/share/man/jrunscript.1 create mode 100644 src/java.scripting/share/man/jrunscript.md create mode 100644 src/java.security.jgss/windows/man/kinit.md create mode 100644 src/java.security.jgss/windows/man/klist.md create mode 100644 src/java.security.jgss/windows/man/ktab.md create mode 100644 src/jdk.accessibility/windows/man/jabswitch.md create mode 100644 src/jdk.accessibility/windows/man/jaccessinspector.md create mode 100644 src/jdk.accessibility/windows/man/jaccesswalker.md delete mode 100644 src/jdk.compiler/share/man/javac.1 create mode 100644 src/jdk.compiler/share/man/javac.md delete mode 100644 src/jdk.compiler/share/man/serialver.1 create mode 100644 src/jdk.compiler/share/man/serialver.md delete mode 100644 src/jdk.hotspot.agent/share/man/jhsdb.1 create mode 100644 src/jdk.hotspot.agent/share/man/jhsdb.md delete mode 100644 src/jdk.httpserver/share/man/jwebserver.1 create mode 100644 src/jdk.httpserver/share/man/jwebserver.md delete mode 100644 src/jdk.jartool/share/man/jar.1 create mode 100644 src/jdk.jartool/share/man/jar.md delete mode 100644 src/jdk.jartool/share/man/jarsigner.1 create mode 100644 src/jdk.jartool/share/man/jarsigner.md delete mode 100644 src/jdk.javadoc/share/man/javadoc.1 create mode 100644 src/jdk.javadoc/share/man/javadoc.md delete mode 100644 src/jdk.jcmd/share/man/jcmd.1 create mode 100644 src/jdk.jcmd/share/man/jcmd.md delete mode 100644 src/jdk.jcmd/share/man/jinfo.1 create mode 100644 src/jdk.jcmd/share/man/jinfo.md delete mode 100644 src/jdk.jcmd/share/man/jmap.1 create mode 100644 src/jdk.jcmd/share/man/jmap.md delete mode 100644 src/jdk.jcmd/share/man/jps.1 create mode 100644 src/jdk.jcmd/share/man/jps.md delete mode 100644 src/jdk.jcmd/share/man/jstack.1 create mode 100644 src/jdk.jcmd/share/man/jstack.md delete mode 100644 src/jdk.jcmd/share/man/jstat.1 create mode 100644 src/jdk.jcmd/share/man/jstat.md delete mode 100644 src/jdk.jconsole/share/man/jconsole.1 create mode 100644 src/jdk.jconsole/share/man/jconsole.md delete mode 100644 src/jdk.jdeps/share/man/javap.1 create mode 100644 src/jdk.jdeps/share/man/javap.md delete mode 100644 src/jdk.jdeps/share/man/jdeprscan.1 create mode 100644 src/jdk.jdeps/share/man/jdeprscan.md delete mode 100644 src/jdk.jdeps/share/man/jdeps.1 create mode 100644 src/jdk.jdeps/share/man/jdeps.md delete mode 100644 src/jdk.jdeps/share/man/jnativescan.1 create mode 100644 src/jdk.jdeps/share/man/jnativescan.md delete mode 100644 src/jdk.jdi/share/man/jdb.1 create mode 100644 src/jdk.jdi/share/man/jdb.md delete mode 100644 src/jdk.jfr/share/man/jfr.1 create mode 100644 src/jdk.jfr/share/man/jfr.md delete mode 100644 src/jdk.jlink/share/man/jlink.1 create mode 100644 src/jdk.jlink/share/man/jlink.md delete mode 100644 src/jdk.jlink/share/man/jmod.1 create mode 100644 src/jdk.jlink/share/man/jmod.md delete mode 100644 src/jdk.jpackage/share/man/jpackage.1 create mode 100644 src/jdk.jpackage/share/man/jpackage.md delete mode 100644 src/jdk.jshell/share/man/jshell.1 create mode 100644 src/jdk.jshell/share/man/jshell.md delete mode 100644 src/jdk.jstatd/share/man/jstatd.1 create mode 100644 src/jdk.jstatd/share/man/jstatd.md diff --git a/make/common/modules/LauncherCommon.gmk b/make/common/modules/LauncherCommon.gmk index aa721a683d7..b522df076f3 100644 --- a/make/common/modules/LauncherCommon.gmk +++ b/make/common/modules/LauncherCommon.gmk @@ -178,10 +178,8 @@ ifeq ($(call isTargetOsType, unix)+$(MAKEFILE_PREFIX), true+Launcher) # We assume all our man pages should reside in section 1. MAN_FILES_MD := $(wildcard $(addsuffix /*.md, $(call FindModuleManDirs, $(MODULE)))) - MAN_FILES_TROFF := $(wildcard $(addsuffix /*.1, $(call FindModuleManDirs, $(MODULE)))) ifneq ($(MAN_FILES_MD), ) - # If we got markdown files, ignore the troff files ifeq ($(ENABLE_PANDOC), false) $(info Warning: pandoc not found. Not generating man pages) else @@ -226,13 +224,5 @@ ifeq ($(call isTargetOsType, unix)+$(MAKEFILE_PREFIX), true+Launcher) TARGETS += $(BUILD_MAN_PAGES) endif - else - # No markdown man pages present - $(eval $(call SetupCopyFiles, COPY_MAN_PAGES, \ - DEST := $(SUPPORT_OUTPUTDIR)/modules_man/$(MODULE)/man1, \ - FILES := $(MAN_FILES_TROFF), \ - )) - - TARGETS += $(COPY_MAN_PAGES) endif endif diff --git a/src/java.base/share/man/java.1 b/src/java.base/share/man/java.1 deleted file mode 100644 index da7fb86099f..00000000000 --- a/src/java.base/share/man/java.1 +++ /dev/null @@ -1,5409 +0,0 @@ -.\" Copyright (c) 1994, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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. -.\" -'\" t -.\" Automatically generated by Pandoc 2.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JAVA" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -java - launch a Java application -.SH SYNOPSIS -.PP -To launch a class file: -.PP -\f[V]java\f[R] [\f[I]options\f[R]] \f[I]mainclass\f[R] [\f[I]args\f[R] -\&...] -.PP -To launch the main class in a JAR file: -.PP -\f[V]java\f[R] [\f[I]options\f[R]] \f[V]-jar\f[R] \f[I]jarfile\f[R] -[\f[I]args\f[R] ...] -.PP -To launch the main class in a module: -.PP -\f[V]java\f[R] [\f[I]options\f[R]] \f[V]-m\f[R] -\f[I]module\f[R][\f[V]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...] -.PP -or -.PP -\f[V]java\f[R] [\f[I]options\f[R]] \f[V]--module\f[R] -\f[I]module\f[R][\f[V]/\f[R]\f[I]mainclass\f[R]] [\f[I]args\f[R] ...] -.PP -To launch a source-file program: -.PP -\f[V]java\f[R] [\f[I]options\f[R]] \f[I]source-file\f[R] [\f[I]args\f[R] -\&...] -.TP -\f[I]options\f[R] -Optional: Specifies command-line options separated by spaces. -See \f[B]Overview of Java Options\f[R] for a description of available -options. -.TP -\f[I]mainclass\f[R] -Specifies the name of the class to be launched. -Command-line entries following \f[V]classname\f[R] are the arguments for -the main method. -.TP -\f[V]-jar\f[R] \f[I]jarfile\f[R] -Executes a program encapsulated in a JAR file. -The \f[I]jarfile\f[R] argument is the name of a JAR file with a manifest -that contains a line in the form -\f[V]Main-Class:\f[R]\f[I]classname\f[R] that defines the class with the -\f[V]public static void main(String[] args)\f[R] method that serves as -your application\[aq]s starting point. -When you use \f[V]-jar\f[R], the specified JAR file is the source of all -user classes, and other class path settings are ignored. -If you\[aq]re using JAR files, then see \f[B]jar\f[R]. -.TP -\f[V]-m\f[R] or \f[V]--module\f[R] \f[I]module\f[R][\f[V]/\f[R]\f[I]mainclass\f[R]] -Executes the main class in a module specified by \f[I]mainclass\f[R] if -it is given, or, if it is not given, the value in the \f[I]module\f[R]. -In other words, \f[I]mainclass\f[R] can be used when it is not specified -by the module, or to override the value when it is specified. -.RS -.PP -See \f[B]Standard Options for Java\f[R]. -.RE -.TP -\f[I]source-file\f[R] -Only used to launch a source-file program. -Specifies the source file that contains the main class when using -source-file mode. -See \f[B]Using Source-File Mode to Launch Source-Code Programs\f[R] -.TP -\f[I]args\f[R] ... -Optional: Arguments following \f[I]mainclass\f[R], -\f[I]source-file\f[R], \f[V]-jar\f[R] \f[I]jarfile\f[R], and -\f[V]-m\f[R] or \f[V]--module\f[R] -\f[I]module\f[R]\f[V]/\f[R]\f[I]mainclass\f[R] are passed as arguments -to the main class. -.SH DESCRIPTION -.PP -The \f[V]java\f[R] command starts a Java application. -It does this by starting the Java Virtual Machine (JVM), loading the -specified class, and calling that class\[aq]s \f[V]main()\f[R] method. -The method must be declared \f[V]public\f[R] and \f[V]static\f[R], it -must not return any value, and it must accept a \f[V]String\f[R] array -as a parameter. -The method declaration has the following form: -.RS -.PP -\f[V]public static void main(String[] args)\f[R] -.RE -.PP -In source-file mode, the \f[V]java\f[R] command can launch a class -declared in a source file. -See \f[B]Using Source-File Mode to Launch Source-Code Programs\f[R] for -a description of using the source-file mode. -.RS -.PP -\f[B]Note:\f[R] You can use the \f[V]JDK_JAVA_OPTIONS\f[R] launcher -environment variable to prepend its content to the actual command line -of the \f[V]java\f[R] launcher. -See \f[B]Using the JDK_JAVA_OPTIONS Launcher Environment Variable\f[R]. -.RE -.PP -By default, the first argument that isn\[aq]t an option of the -\f[V]java\f[R] command is the fully qualified name of the class to be -called. -If \f[V]-jar\f[R] is specified, then its argument is the name of the JAR -file containing class and resource files for the application. -The startup class must be indicated by the \f[V]Main-Class\f[R] manifest -header in its manifest file. -.PP -Arguments after the class file name or the JAR file name are passed to -the \f[V]main()\f[R] method. -.SS \f[V]javaw\f[R] -.PP -\f[B]Windows:\f[R] The \f[V]javaw\f[R] command is identical to -\f[V]java\f[R], except that with \f[V]javaw\f[R] there\[aq]s no -associated console window. -Use \f[V]javaw\f[R] when you don\[aq]t want a command prompt window to -appear. -The \f[V]javaw\f[R] launcher will, however, display a dialog box with -error information if a launch fails. -.SH USING SOURCE-FILE MODE TO LAUNCH SOURCE-CODE PROGRAMS -.PP -To launch a class declared in a source file, run the \f[V]java\f[R] -launcher in source-file mode. -Entering source-file mode is determined by two items on the -\f[V]java\f[R] command line: -.IP \[bu] 2 -The first item on the command line that is not an option or part of an -option. -In other words, the item in the command line that would otherwise be the -main class name. -.IP \[bu] 2 -The \f[V]--source\f[R] \f[I]version\f[R] option, if present. -.PP -If the class identifies an existing file that has a \f[V].java\f[R] -extension, or if the \f[V]--source\f[R] option is specified, then -source-file mode is selected. -The source file is then compiled and run. -The \f[V]--source\f[R] option can be used to specify the source -\f[I]version\f[R] or \f[I]N\f[R] of the source code. -This determines the API that can be used. -When you set \f[V]--source\f[R] \f[I]N\f[R], you can only use the public -API that was defined in JDK \f[I]N\f[R]. -.RS -.PP -\f[B]Note:\f[R] The valid values of \f[I]N\f[R] change for each release, -with new values added and old values removed. -You\[aq]ll get an error message if you use a value of \f[I]N\f[R] that -is no longer supported. -The supported values of \f[I]N\f[R] are the current Java SE release -(\f[V]24\f[R]) and a limited number of previous releases, detailed in -the command-line help for \f[V]javac\f[R], under the \f[V]--source\f[R] -and \f[V]--release\f[R] options. -.RE -.PP -If the file does not have the \f[V].java\f[R] extension, the -\f[V]--source\f[R] option must be used to tell the \f[V]java\f[R] -command to use the source-file mode. -The \f[V]--source\f[R] option is used for cases when the source file is -a \[dq]script\[dq] to be executed and the name of the source file does -not follow the normal naming conventions for Java source files. -.PP -In source-file mode, the effect is as though the source file is compiled -into memory, and the first class found in the source file is executed. -Any arguments placed after the name of the source file in the original -command line are passed to the compiled class when it is executed. -.PP -For example, if a file were named \f[V]HelloWorld.java\f[R] and -contained a class named \f[V]HelloWorld\f[R], then the source-file mode -command to launch the class would be: -.RS -.PP -\f[V]java HelloWorld.java\f[R] -.RE -.PP -This use of source-file mode is informally equivalent to using the -following two commands: -.IP -.nf -\f[CB] -javac -d --source-path HelloWorld.java -java --class-path HelloWorld -\f[R] -.fi -.PP -where \f[V]\f[R] is computed -.PP -\f[B]In source-file mode, any additional command-line options are -processed as follows:\f[R] -.IP \[bu] 2 -The launcher scans the options specified before the source file for any -that are relevant in order to compile the source file. -.RS 2 -.PP -This includes: \f[V]--class-path\f[R], \f[V]--module-path\f[R], -\f[V]--add-exports\f[R], \f[V]--add-modules\f[R], -\f[V]--limit-modules\f[R], \f[V]--patch-module\f[R], -\f[V]--upgrade-module-path\f[R], and any variant forms of those options. -It also includes the new \f[V]--enable-preview\f[R] option, described in -JEP 12. -.RE -.IP \[bu] 2 -No provision is made to pass any additional options to the compiler, -such as \f[V]-processor\f[R] or \f[V]-Werror\f[R]. -.IP \[bu] 2 -Command-line argument files (\f[V]\[at]\f[R]-files) may be used in the -standard way. -Long lists of arguments for either the VM or the program being invoked -may be placed in files specified on the command-line by prefixing the -filename with an \f[V]\[at]\f[R] character. -.PP -\f[B]In source-file mode, compilation proceeds as follows:\f[R] -.IP \[bu] 2 -Any command-line options that are relevant to the compilation -environment are taken into account. -These include: -\f[V]--class-path\f[R]/\f[V]-classpath\f[R]/\f[V]-cp\f[R], -\f[V]--module-path\f[R]/\f[V]-p\f[R], \f[V]--add-exports\f[R], -\f[V]--add-modules\f[R], \f[V]--limit-modules\f[R], -\f[V]--patch-module\f[R], \f[V]--upgrade-module-path\f[R], -\f[V]--enable-preview\f[R]. -.IP \[bu] 2 -The root of the source tree, \f[V]\f[R] is computed from -the package of the class being launched. -For example, if \f[V]HelloWorld.java\f[R] declared its classes to be in -the \f[V]hello\f[R] package, then the file \f[V]HelloWorld.java\f[R] is -expected to reside in the directory \f[V]somedir/hello/\f[R]. -In this case, \f[V]somedir\f[R] is computed to be the root of the source -tree. -.IP \[bu] 2 -The root of the source tree serves as the source-path for compilation, -so that other source files found in that tree and are needed by -\f[V]HelloWorld\f[R] could be compiled. -.IP \[bu] 2 -Annotation processing is disabled, as if \f[V]-proc:none\f[R] is in -effect. -.IP \[bu] 2 -If a version is specified, via the \f[V]--source\f[R] option, the value -is used as the argument for an implicit \f[V]--release\f[R] option for -the compilation. -This sets both the source version accepted by compiler and the system -API that may be used by the code in the source file. -.IP \[bu] 2 -If \f[V]--enable-preview\f[R] is specified, the \f[V]--source N\f[R] -arguments can be omitted. -If the Java runtime version is \f[V]N\f[R], then \f[V]--release N\f[R] -is implied when compiling source files. -.IP \[bu] 2 -If a \f[V]module-info.java\f[R] file exists in the -\f[V]\f[R] directory, its module declaration is used to -define a named module that will contain all the classes compiled from -\f[V].java\f[R] files in the source tree. -If \f[V]module-info.java\f[R] does not exist, all the classes compiled -from source files will be compiled in the context of the unnamed module. -.IP \[bu] 2 -The source file that is launched should contain one or more top-level -classes, the first of which is taken as the class to be executed. -.IP \[bu] 2 -For the source file that is launched, the compiler does not enforce the -optional restriction defined at the end of JLS 7.6, that a type in a -named package should exist in a file whose name is composed from the -type name followed by the \f[V].java\f[R] extension. -.IP \[bu] 2 -If a source file contains errors, appropriate error messages are written -to the standard error stream, and the launcher exits with a non-zero -exit code. -.PP -\f[B]In source-file mode, execution proceeds as follows:\f[R] -.IP \[bu] 2 -The class to be executed is the first top-level class found in the -source file. -It must contain a declaration of an entry \f[V]main\f[R] method. -.IP \[bu] 2 -The compiled classes are loaded by a custom class loader, that delegates -to the application class loader. -This implies that classes appearing on the application class path cannot -refer to any classes declared in source files. -.IP \[bu] 2 -If a \f[V]module-info.java\f[R] file exists in the -\f[V]\f[R] directory, then all the classes compiled from -\f[V].java\f[R] files in the source tree will be in that module, which -will serve as the root module for the execution of the program. -If \f[V]module-info.java\f[R] does not exist, the compiled classes are -executed in the context of an unnamed module, as though -\f[V]--add-modules=ALL-DEFAULT\f[R] is in effect. -This is in addition to any other \f[V]--add-module\f[R] options that may -be have been specified on the command line. -.IP \[bu] 2 -Any arguments appearing after the name of the file on the command line -are passed to the main method in the obvious way. -.IP \[bu] 2 -It is an error if there is a class on the application class path whose -name is the same as that of the class to be executed. -.PP -See \f[B]JEP 458: Launch Multi-File Source-Code Programs\f[R] -[https://openjdk.org/jeps/458] for complete details. -.SH USING THE JDK_JAVA_OPTIONS LAUNCHER ENVIRONMENT VARIABLE -.PP -\f[V]JDK_JAVA_OPTIONS\f[R] prepends its content to the options parsed -from the command line. -The content of the \f[V]JDK_JAVA_OPTIONS\f[R] environment variable is a -list of arguments separated by white-space characters (as determined by -\f[V]isspace()\f[R]). -These are prepended to the command line arguments passed to -\f[V]java\f[R] launcher. -The encoding requirement for the environment variable is the same as the -\f[V]java\f[R] command line on the system. -\f[V]JDK_JAVA_OPTIONS\f[R] environment variable content is treated in -the same manner as that specified in the command line. -.PP -Single (\f[V]\[aq]\f[R]) or double (\f[V]\[dq]\f[R]) quotes can be used -to enclose arguments that contain whitespace characters. -All content between the open quote and the first matching close quote -are preserved by simply removing the pair of quotes. -In case a matching quote is not found, the launcher will abort with an -error message. -\f[V]\[at]\f[R]-files are supported as they are specified in the command -line. -However, as in \f[V]\[at]\f[R]-files, use of a wildcard is not -supported. -In order to mitigate potential misuse of \f[V]JDK_JAVA_OPTIONS\f[R] -behavior, options that specify the main class (such as \f[V]-jar\f[R]) -or cause the \f[V]java\f[R] launcher to exit without executing the main -class (such as \f[V]-h\f[R]) are disallowed in the environment variable. -If any of these options appear in the environment variable, the launcher -will abort with an error message. -When \f[V]JDK_JAVA_OPTIONS\f[R] is set, the launcher prints a message to -stderr as a reminder. -.PP -\f[B]Example:\f[R] -.IP -.nf -\f[CB] -$ export JDK_JAVA_OPTIONS=\[aq]-g \[at]file1 -Dprop=value \[at]file2 -Dws.prop=\[dq]white spaces\[dq]\[aq] -$ java -Xint \[at]file3 -\f[R] -.fi -.PP -is equivalent to the command line: -.IP -.nf -\f[CB] -java -g \[at]file1 -Dprop=value \[at]file2 -Dws.prop=\[dq]white spaces\[dq] -Xint \[at]file3 -\f[R] -.fi -.SH OVERVIEW OF JAVA OPTIONS -.PP -The \f[V]java\f[R] command supports a wide range of options in the -following categories: -.IP \[bu] 2 -\f[B]Standard Options for Java\f[R]: Options guaranteed to be supported -by all implementations of the Java Virtual Machine (JVM). -They\[aq]re used for common actions, such as checking the version of the -JRE, setting the class path, enabling verbose output, and so on. -.IP \[bu] 2 -\f[B]Extra Options for Java\f[R]: General purpose options that are -specific to the Java HotSpot Virtual Machine. -They aren\[aq]t guaranteed to be supported by all JVM implementations, -and are subject to change. -These options start with \f[V]-X\f[R]. -.PP -The advanced options aren\[aq]t recommended for casual use. -These are developer options used for tuning specific areas of the Java -HotSpot Virtual Machine operation that often have specific system -requirements and may require privileged access to system configuration -parameters. -Several examples of performance tuning are provided in \f[B]Performance -Tuning Examples\f[R]. -These options aren\[aq]t guaranteed to be supported by all JVM -implementations and are subject to change. -Advanced options start with \f[V]-XX\f[R]. -.IP \[bu] 2 -\f[B]Advanced Runtime Options for Java\f[R]: Control the runtime -behavior of the Java HotSpot VM. -.IP \[bu] 2 -\f[B]Advanced JIT Compiler Options for java\f[R]: Control the dynamic -just-in-time (JIT) compilation performed by the Java HotSpot VM. -.IP \[bu] 2 -\f[B]Advanced Serviceability Options for Java\f[R]: Enable gathering -system information and performing extensive debugging. -.IP \[bu] 2 -\f[B]Advanced Garbage Collection Options for Java\f[R]: Control how -garbage collection (GC) is performed by the Java HotSpot -.PP -Boolean options are used to either enable a feature that\[aq]s disabled -by default or disable a feature that\[aq]s enabled by default. -Such options don\[aq]t require a parameter. -Boolean \f[V]-XX\f[R] options are enabled using the plus sign -(\f[V]-XX:+\f[R]\f[I]OptionName\f[R]) and disabled using the minus sign -(\f[V]-XX:-\f[R]\f[I]OptionName\f[R]). -.PP -For options that require an argument, the argument may be separated from -the option name by a space, a colon (:), or an equal sign (=), or the -argument may directly follow the option (the exact syntax differs for -each option). -If you\[aq]re expected to specify the size in bytes, then you can use no -suffix, or use the suffix \f[V]k\f[R] or \f[V]K\f[R] for kilobytes (KB), -\f[V]m\f[R] or \f[V]M\f[R] for megabytes (MB), or \f[V]g\f[R] or -\f[V]G\f[R] for gigabytes (GB). -For example, to set the size to 8 GB, you can specify either -\f[V]8g\f[R], \f[V]8192m\f[R], \f[V]8388608k\f[R], or -\f[V]8589934592\f[R] as the argument. -If you are expected to specify the percentage, then use a number from 0 -to 1. -For example, specify \f[V]0.25\f[R] for 25%. -.PP -The following sections describe the options that are deprecated, -obsolete, and removed: -.IP \[bu] 2 -\f[B]Deprecated Java Options\f[R]: Accepted and acted upon --- a warning -is issued when they\[aq]re used. -.IP \[bu] 2 -\f[B]Obsolete Java Options\f[R]: Accepted but ignored --- a warning is -issued when they\[aq]re used. -.IP \[bu] 2 -\f[B]Removed Java Options\f[R]: Removed --- using them results in an -error. -.SH STANDARD OPTIONS FOR JAVA -.PP -These are the most commonly used options supported by all -implementations of the JVM. -.RS -.PP -\f[B]Note:\f[R] To specify an argument for a long option, you can use -either \f[V]--\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R] or -\f[V]--\f[R]\f[I]name\f[R] \f[I]value\f[R]. -.RE -.TP -\f[V]-agentlib:\f[R]\f[I]libname\f[R][\f[V]=\f[R]\f[I]options\f[R]] -Loads the specified native agent library. -After the library name, a comma-separated list of options specific to -the library can be used. -If the option \f[V]-agentlib:foo\f[R] is specified, then the JVM -attempts to load the library named \f[V]foo\f[R] using the platform -specific naming conventions and locations: -.RS -.IP \[bu] 2 -\f[B]Linux and other POSIX-like platforms:\f[R] The JVM attempts to load -the library named \f[V]libfoo.so\f[R] in the location specified by the -\f[V]LD_LIBRARY_PATH\f[R] system variable. -.IP \[bu] 2 -\f[B]macOS:\f[R] The JVM attempts to load the library named -\f[V]libfoo.dylib\f[R] in the location specified by the -\f[V]DYLD_LIBRARY_PATH\f[R] system variable. -.IP \[bu] 2 -\f[B]Windows:\f[R] The JVM attempts to load the library named -\f[V]foo.dll\f[R] in the location specified by the \f[V]PATH\f[R] system -variable. -.RS 2 -.PP -The following example shows how to load the Java Debug Wire Protocol -(JDWP) library and listen for the socket connection on port 8000, -suspending the JVM before the main class loads: -.RS -.PP -\f[V]-agentlib:jdwp=transport=dt_socket,server=y,address=8000\f[R] -.RE -.RE -.RE -.TP -\f[V]-agentpath:\f[R]\f[I]pathname\f[R][\f[V]=\f[R]\f[I]options\f[R]] -Loads the native agent library specified by the absolute path name. -This option is equivalent to \f[V]-agentlib\f[R] but uses the full path -and file name of the library. -.TP -\f[V]--class-path\f[R] \f[I]classpath\f[R], \f[V]-classpath\f[R] \f[I]classpath\f[R], or \f[V]-cp\f[R] \f[I]classpath\f[R] -Specifies a list of directories, JAR files, and ZIP archives to search -for class files. -.RS -.PP -On Windows, semicolons (\f[V];\f[R]) separate entities in this list; on -other platforms it is a colon (\f[V]:\f[R]). -.PP -Specifying \f[I]classpath\f[R] overrides any setting of the -\f[V]CLASSPATH\f[R] environment variable. -If the class path option isn\[aq]t used and \f[I]classpath\f[R] -isn\[aq]t set, then the user class path consists of the current -directory (.). -.PP -As a special convenience, a class path element that contains a base name -of an asterisk (*) is considered equivalent to specifying a list of all -the files in the directory with the extension \f[V].jar\f[R] or -\f[V].JAR\f[R] . -A Java program can\[aq]t tell the difference between the two -invocations. -For example, if the directory mydir contains \f[V]a.jar\f[R] and -\f[V]b.JAR\f[R], then the class path element mydir/* is expanded to -\f[V]A.jar:b.JAR\f[R], except that the order of JAR files is -unspecified. -All \f[V].jar\f[R] files in the specified directory, even hidden ones, -are included in the list. -A class path entry consisting of an asterisk (*) expands to a list of -all the jar files in the current directory. -The \f[V]CLASSPATH\f[R] environment variable, where defined, is -similarly expanded. -Any class path wildcard expansion that occurs before the Java VM is -started. -Java programs never see wildcards that aren\[aq]t expanded except by -querying the environment, such as by calling -\f[V]System.getenv(\[dq]CLASSPATH\[dq])\f[R]. -.RE -.TP -\f[V]--disable-\[at]files\f[R] -Can be used anywhere on the command line, including in an argument file, -to prevent further \f[V]\[at]filename\f[R] expansion. -This option stops expanding \f[V]\[at]\f[R]-argfiles after the option. -.TP -\f[V]--enable-preview\f[R] -Allows classes to depend on \f[B]preview features\f[R] -[https://docs.oracle.com/en/java/javase/12/language/index.html#JSLAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] -of the release. -.TP -\f[V]--enable-native-access\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...] -Native access involves access to code or data outside the Java runtime. -This is generally unsafe and, if done incorrectly, might crash the JVM -or result in memory corruption. -Native access can occur as a result of calling a method that is either -\f[B]restricted\f[R] [https://openjdk.org/jeps/454#Safety], or -\f[V]native\f[R]. -This option allows code in the specified modules to perform native -access. -Native access occurring in a module that has not been explicitly enabled -is deemed \f[I]illegal\f[R]. -.RS -.PP -\f[I]module\f[R] can be a module name, or \f[V]ALL-UNNAMED\f[R] to -indicate code on the class path. -.RE -.TP --\f[V]--illegal-native-access=\f[R]\f[I]parameter\f[R] -This option specifies a mode for how illegal native access is handled: -.RS -.RS -.PP -\f[B]Note:\f[R] This option will be removed in a future release. -.RE -.IP \[bu] 2 -\f[V]allow\f[R]: This mode allows illegal native access in all modules, -without any warings. -.IP \[bu] 2 -\f[V]warn\f[R]: This mode is identical to \f[V]allow\f[R] except that a -warning message is issued for the first illegal native access found in a -module. -This mode is the default for the current JDK but will change in a future -release. -.IP \[bu] 2 -\f[V]deny\f[R]: This mode disables illegal native access. -That is, any illegal native access causes an -\f[V]IllegalCallerException\f[R]. -This mode will become the default in a future release. -.PP -To verify that your application is ready for a future version of the -JDK, run it with \f[V]--illegal-native-access=deny\f[R] along with any -necessary \f[V]--enable-native-access\f[R] options. -.RE -.TP -\f[V]--finalization=\f[R]\f[I]value\f[R] -Controls whether the JVM performs finalization of objects. -Valid values are \[dq]enabled\[dq] and \[dq]disabled\[dq]. -Finalization is enabled by default, so the value \[dq]enabled\[dq] does -nothing. -The value \[dq]disabled\[dq] disables finalization, so that no -finalizers are invoked. -.TP -\f[V]--module-path\f[R] \f[I]modulepath\f[R]... or \f[V]-p\f[R] \f[I]modulepath\f[R] -Specifies where to find application modules with a list of path -elements. -The elements of a module path can be a file path to a module or a -directory containing modules. -Each module is either a modular JAR or an exploded-module directory. -.RS -.PP -On Windows, semicolons (\f[V];\f[R]) separate path elements in this -list; on other platforms it is a colon (\f[V]:\f[R]). -.RE -.TP -\f[V]--upgrade-module-path\f[R] \f[I]modulepath\f[R]... -Specifies where to find module replacements of upgradeable modules in -the runtime image with a list of path elements. -The elements of a module path can be a file path to a module or a -directory containing modules. -Each module is either a modular JAR or an exploded-module directory. -.RS -.PP -On Windows, semicolons (\f[V];\f[R]) separate path elements in this -list; on other platforms it is a colon (\f[V]:\f[R]). -.RE -.TP -\f[V]--add-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...] -Specifies the root modules to resolve in addition to the initial module. -\f[I]module\f[R] can also be \f[V]ALL-DEFAULT\f[R], -\f[V]ALL-SYSTEM\f[R], and \f[V]ALL-MODULE-PATH\f[R]. -.TP -\f[V]--list-modules\f[R] -Lists the observable modules and then exits. -.TP -\f[V]-d\f[R] \f[I]module_name\f[R] or \f[V]--describe-module\f[R] \f[I]module_name\f[R] -Describes a specified module and then exits. -.TP -\f[V]--dry-run\f[R] -Creates the VM but doesn\[aq]t execute the main method. -This \f[V]--dry-run\f[R] option might be useful for validating the -command-line options such as the module system configuration. -.TP -\f[V]--validate-modules\f[R] -Validates all modules and exit. -This option is helpful for finding conflicts and other errors with -modules on the module path. -.TP -\f[V]-D\f[R]\f[I]property\f[R]\f[V]=\f[R]\f[I]value\f[R] -Sets a system property value. -The \f[I]property\f[R] variable is a string with no spaces that -represents the name of the property. -The \f[I]value\f[R] variable is a string that represents the value of -the property. -If \f[I]value\f[R] is a string with spaces, then enclose it in quotation -marks (for example \f[V]-Dfoo=\[dq]foo bar\[dq]\f[R]). -.TP -\f[V]-disableassertions\f[R][\f[V]:\f[R][\f[I]packagename\f[R]]...|\f[V]:\f[R]\f[I]classname\f[R]] or \f[V]-da\f[R][\f[V]:\f[R][\f[I]packagename\f[R]]...|\f[V]:\f[R]\f[I]classname\f[R]] -Disables assertions. -By default, assertions are disabled in all packages and classes. -With no arguments, \f[V]-disableassertions\f[R] (\f[V]-da\f[R]) disables -assertions in all packages and classes. -With the \f[I]packagename\f[R] argument ending in \f[V]...\f[R], the -switch disables assertions in the specified package and any subpackages. -If the argument is simply \f[V]...\f[R], then the switch disables -assertions in the unnamed package in the current working directory. -With the \f[I]classname\f[R] argument, the switch disables assertions in -the specified class. -.RS -.PP -The \f[V]-disableassertions\f[R] (\f[V]-da\f[R]) option applies to all -class loaders and to system classes (which don\[aq]t have a class -loader). -There\[aq]s one exception to this rule: If the option is provided with -no arguments, then it doesn\[aq]t apply to system classes. -This makes it easy to disable assertions in all classes except for -system classes. -The \f[V]-disablesystemassertions\f[R] option enables you to disable -assertions in all system classes. -To explicitly enable assertions in specific packages or classes, use the -\f[V]-enableassertions\f[R] (\f[V]-ea\f[R]) option. -Both options can be used at the same time. -For example, to run the \f[V]MyClass\f[R] application with assertions -enabled in the package \f[V]com.wombat.fruitbat\f[R] (and any -subpackages) but disabled in the class -\f[V]com.wombat.fruitbat.Brickbat\f[R], use the following command: -.RS -.PP -\f[V]java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat MyClass\f[R] -.RE -.RE -.TP -\f[V]-disablesystemassertions\f[R] or \f[V]-dsa\f[R] -Disables assertions in all system classes. -.TP -\f[V]-enableassertions\f[R][\f[V]:\f[R][\f[I]packagename\f[R]]...|\f[V]:\f[R]\f[I]classname\f[R]] or \f[V]-ea\f[R][\f[V]:\f[R][\f[I]packagename\f[R]]...|\f[V]:\f[R]\f[I]classname\f[R]] -Enables assertions. -By default, assertions are disabled in all packages and classes. -With no arguments, \f[V]-enableassertions\f[R] (\f[V]-ea\f[R]) enables -assertions in all packages and classes. -With the \f[I]packagename\f[R] argument ending in \f[V]...\f[R], the -switch enables assertions in the specified package and any subpackages. -If the argument is simply \f[V]...\f[R], then the switch enables -assertions in the unnamed package in the current working directory. -With the \f[I]classname\f[R] argument, the switch enables assertions in -the specified class. -.RS -.PP -The \f[V]-enableassertions\f[R] (\f[V]-ea\f[R]) option applies to all -class loaders and to system classes (which don\[aq]t have a class -loader). -There\[aq]s one exception to this rule: If the option is provided with -no arguments, then it doesn\[aq]t apply to system classes. -This makes it easy to enable assertions in all classes except for system -classes. -The \f[V]-enablesystemassertions\f[R] option provides a separate switch -to enable assertions in all system classes. -To explicitly disable assertions in specific packages or classes, use -the \f[V]-disableassertions\f[R] (\f[V]-da\f[R]) option. -If a single command contains multiple instances of these switches, then -they\[aq]re processed in order, before loading any classes. -For example, to run the \f[V]MyClass\f[R] application with assertions -enabled only in the package \f[V]com.wombat.fruitbat\f[R] (and any -subpackages) but disabled in the class -\f[V]com.wombat.fruitbat.Brickbat\f[R], use the following command: -.RS -.PP -\f[V]java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat MyClass\f[R] -.RE -.RE -.TP -\f[V]-enablesystemassertions\f[R] or \f[V]-esa\f[R] -Enables assertions in all system classes. -.TP -\f[V]-help\f[R], \f[V]-h\f[R], or \f[V]-?\f[R] -Prints the help message to the error stream. -.TP -\f[V]--help\f[R] -Prints the help message to the output stream. -.TP -\f[V]-javaagent:\f[R]\f[I]jarpath\f[R][\f[V]=\f[R]\f[I]options\f[R]] -Loads the specified Java programming language agent. -See \f[V]java.lang.instrument\f[R]. -.TP -\f[V]--show-version\f[R] -Prints the product version to the output stream and continues. -.TP -\f[V]-showversion\f[R] -Prints the product version to the error stream and continues. -.TP -\f[V]--show-module-resolution\f[R] -Shows module resolution output during startup. -.TP -\f[V]-splash:\f[R]\f[I]imagepath\f[R] -Shows the splash screen with the image specified by \f[I]imagepath\f[R]. -HiDPI scaled images are automatically supported and used if available. -The unscaled image file name, such as \f[V]image.ext\f[R], should always -be passed as the argument to the \f[V]-splash\f[R] option. -The most appropriate scaled image provided is picked up automatically. -.RS -.PP -For example, to show the \f[V]splash.gif\f[R] file from the -\f[V]images\f[R] directory when starting your application, use the -following option: -.RS -.PP -\f[V]-splash:images/splash.gif\f[R] -.RE -.PP -See the SplashScreen API documentation for more information. -.RE -.TP -\f[V]-verbose:class\f[R] -Displays information about each loaded class. -.TP -\f[V]-verbose:gc\f[R] -Displays information about each garbage collection (GC) event. -.TP -\f[V]-verbose:jni\f[R] -Displays information about the use of native methods and other Java -Native Interface (JNI) activity. -.TP -\f[V]-verbose:module\f[R] -Displays information about the modules in use. -.TP -\f[V]--version\f[R] -Prints product version to the output stream and exits. -.TP -\f[V]-version\f[R] -Prints product version to the error stream and exits. -.TP -\f[V]-X\f[R] -Prints the help on extra options to the error stream. -.TP -\f[V]--help-extra\f[R] -Prints the help on extra options to the output stream. -.TP -\f[V]\[at]\f[R]\f[I]argfile\f[R] -Specifies one or more argument files prefixed by \f[V]\[at]\f[R] used by -the \f[V]java\f[R] command. -It isn\[aq]t uncommon for the \f[V]java\f[R] command line to be very -long because of the \f[V].jar\f[R] files needed in the classpath. -The \f[V]\[at]\f[R]\f[I]argfile\f[R] option overcomes command-line -length limitations by enabling the launcher to expand the contents of -argument files after shell expansion, but before argument processing. -Contents in the argument files are expanded because otherwise, they -would be specified on the command line until the -\f[V]--disable-\[at]files\f[R] option was encountered. -.RS -.PP -The argument files can also contain the main class name and all options. -If an argument file contains all of the options required by the -\f[V]java\f[R] command, then the command line could simply be: -.RS -.PP -\f[V]java \[at]\f[R]\f[I]argfile\f[R] -.RE -.PP -See \f[B]java Command-Line Argument Files\f[R] for a description and -examples of using \f[V]\[at]\f[R]-argfiles. -.RE -.SH EXTRA OPTIONS FOR JAVA -.PP -The following \f[V]java\f[R] options are general purpose options that -are specific to the Java HotSpot Virtual Machine. -.TP -\f[V]-Xbatch\f[R] -Disables background compilation. -By default, the JVM compiles the method as a background task, running -the method in interpreter mode until the background compilation is -finished. -The \f[V]-Xbatch\f[R] flag disables background compilation so that -compilation of all methods proceeds as a foreground task until -completed. -This option is equivalent to \f[V]-XX:-BackgroundCompilation\f[R]. -.TP -\f[V]-Xbootclasspath/a:\f[R]\f[I]directories\f[R]|\f[I]zip\f[R]|\f[I]JAR-files\f[R] -Specifies a list of directories, JAR files, and ZIP archives to append -to the end of the default bootstrap class path. -.RS -.PP -On Windows, semicolons (\f[V];\f[R]) separate entities in this list; on -other platforms it is a colon (\f[V]:\f[R]). -.RE -.TP -\f[V]-Xcheck:jni\f[R] -Performs additional checks for Java Native Interface (JNI) functions. -.RS -.PP -The following checks are considered indicative of significant problems -with the native code, and the JVM terminates with an irrecoverable error -in such cases: -.IP \[bu] 2 -The thread doing the call is not attached to the JVM. -.IP \[bu] 2 -The thread doing the call is using the \f[V]JNIEnv\f[R] belonging to -another thread. -.IP \[bu] 2 -A parameter validation check fails: -.RS 2 -.IP \[bu] 2 -A \f[V]jfieldID\f[R], or \f[V]jmethodID\f[R], is detected as being -invalid. -For example: -.RS 2 -.IP \[bu] 2 -Of the wrong type -.IP \[bu] 2 -Associated with the wrong class -.RE -.IP \[bu] 2 -A parameter of the wrong type is detected. -.IP \[bu] 2 -An invalid parameter value is detected. -For example: -.RS 2 -.IP \[bu] 2 -NULL where not permitted -.IP \[bu] 2 -An out-of-bounds array index, or frame capacity -.IP \[bu] 2 -A non-UTF-8 string -.IP \[bu] 2 -An invalid JNI reference -.IP \[bu] 2 -An attempt to use a \f[V]ReleaseXXX\f[R] function on a parameter not -produced by the corresponding \f[V]GetXXX\f[R] function -.RE -.RE -.PP -The following checks only result in warnings being printed: -.IP \[bu] 2 -A JNI call was made without checking for a pending exception from a -previous JNI call, and the current call is not safe when an exception -may be pending. -.IP \[bu] 2 -A class descriptor is in decorated format (\f[V]Lname;\f[R]) when it -should not be. -.IP \[bu] 2 -A \f[V]NULL\f[R] parameter is allowed, but its use is questionable. -.IP \[bu] 2 -Calling other JNI functions in the scope of -\f[V]Get/ReleasePrimitiveArrayCritical\f[R] or -\f[V]Get/ReleaseStringCritical\f[R] -.PP -Expect a performance degradation when this option is used. -.RE -.TP -\f[V]-Xcomp\f[R] -Testing mode to exercise JIT compilers. -This option should not be used in production environments. -.TP -\f[V]-Xdebug\f[R] -Does nothing; deprecated for removal in a future release. -.TP -\f[V]-Xdiag\f[R] -Shows additional diagnostic messages. -.TP -\f[V]-Xint\f[R] -Runs the application in interpreted-only mode. -Compilation to native code is disabled, and all bytecode is executed by -the interpreter. -The performance benefits offered by the just-in-time (JIT) compiler -aren\[aq]t present in this mode. -.TP -\f[V]-Xinternalversion\f[R] -Displays more detailed JVM version information than the -\f[V]-version\f[R] option, and then exits. -.TP -\f[V]-Xlog:\f[R]\f[I]option\f[R] -Configure or enable logging with the Java Virtual Machine (JVM) unified -logging framework. -See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R]. -.TP -\f[V]-Xmixed\f[R] -Executes all bytecode by the interpreter except for hot methods, which -are compiled to native code. -On by default. -Use \f[V]-Xint\f[R] to switch off. -.TP -\f[V]-Xmn\f[R] \f[I]size\f[R] -Sets the initial and maximum size (in bytes) of the heap for the young -generation (nursery) in the generational collectors. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The young generation region of the heap is used for new objects. -GC is performed in this region more often than in other regions. -If the size for the young generation is too small, then a lot of minor -garbage collections are performed. -If the size is too large, then only full garbage collections are -performed, which can take a long time to complete. -It is recommended that you do not set the size for the young generation -for the G1 collector, and keep the size for the young generation greater -than 25% and less than 50% of the overall heap size for other -collectors. -The following examples show how to set the initial and maximum size of -young generation to 256 MB using various units: -.RS -.IP -.nf -\f[CB] --Xmn256m --Xmn262144k --Xmn268435456 -\f[R] -.fi -.PP -Instead of the \f[V]-Xmn\f[R] option to set both the initial and maximum -size of the heap for the young generation, you can use -\f[V]-XX:NewSize\f[R] to set the initial size and -\f[V]-XX:MaxNewSize\f[R] to set the maximum size. -.RE -.TP -\f[V]-Xms\f[R] \f[I]size\f[R] -Sets the minimum and the initial size (in bytes) of the heap. -This value must be a multiple of 1024 and greater than 1 MB. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The following examples show how to set the size of allocated memory to 6 -MB using various units: -.RS -.IP -.nf -\f[CB] --Xms6291456 --Xms6144k --Xms6m -\f[R] -.fi -.PP -If you do not set this option, then the initial size will be set as the -sum of the sizes allocated for the old generation and the young -generation. -The initial size of the heap for the young generation can be set using -the \f[V]-Xmn\f[R] option or the \f[V]-XX:NewSize\f[R] option. -.PP -Note that the \f[V]-XX:InitialHeapSize\f[R] option can also be used to -set the initial heap size. -If it appears after \f[V]-Xms\f[R] on the command line, then the initial -heap size gets set to the value specified with -\f[V]-XX:InitialHeapSize\f[R]. -.RE -.TP -\f[V]-Xmx\f[R] \f[I]size\f[R] -Specifies the maximum size (in bytes) of the heap. -This value must be a multiple of 1024 and greater than 2 MB. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value is chosen at runtime based on system configuration. -For server deployments, \f[V]-Xms\f[R] and \f[V]-Xmx\f[R] are often set -to the same value. -The following examples show how to set the maximum allowed size of -allocated memory to 80 MB using various units: -.RS -.IP -.nf -\f[CB] --Xmx83886080 --Xmx81920k --Xmx80m -\f[R] -.fi -.PP -The \f[V]-Xmx\f[R] option is equivalent to \f[V]-XX:MaxHeapSize\f[R]. -.RE -.TP -\f[V]-Xnoclassgc\f[R] -Disables garbage collection (GC) of classes. -This can save some GC time, which shortens interruptions during the -application run. -When you specify \f[V]-Xnoclassgc\f[R] at startup, the class objects in -the application are left untouched during GC and are always be -considered live. -This can result in more memory being permanently occupied which, if not -used carefully, throws an out-of-memory exception. -.TP -\f[V]-Xrs\f[R] -Reduces the use of operating system signals by the JVM. -Shutdown hooks enable the orderly shutdown of a Java application by -running user cleanup code (such as closing database connections) at -shutdown, even if the JVM terminates abruptly. -.RS -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] -.RS 2 -.IP \[bu] 2 -The JVM catches signals to implement shutdown hooks for unexpected -termination. -The JVM uses \f[V]SIGHUP\f[R], \f[V]SIGINT\f[R], and \f[V]SIGTERM\f[R] -to initiate the running of shutdown hooks. -.IP \[bu] 2 -Applications embedding the JVM frequently need to trap signals such as -\f[V]SIGINT\f[R] or \f[V]SIGTERM\f[R], which can lead to interference -with the JVM signal handlers. -The \f[V]-Xrs\f[R] option is available to address this issue. -When \f[V]-Xrs\f[R] is used, the signal masks for \f[V]SIGINT\f[R], -\f[V]SIGTERM\f[R], \f[V]SIGHUP\f[R], and \f[V]SIGQUIT\f[R] aren\[aq]t -changed by the JVM, and signal handlers for these signals aren\[aq]t -installed. -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] -.RS 2 -.IP \[bu] 2 -The JVM watches for console control events to implement shutdown hooks -for unexpected termination. -Specifically, the JVM registers a console control handler that begins -shutdown-hook processing and returns \f[V]TRUE\f[R] for -\f[V]CTRL_C_EVENT\f[R], \f[V]CTRL_CLOSE_EVENT\f[R], -\f[V]CTRL_LOGOFF_EVENT\f[R], and \f[V]CTRL_SHUTDOWN_EVENT\f[R]. -.IP \[bu] 2 -The JVM uses a similar mechanism to implement the feature of dumping -thread stacks for debugging purposes. -The JVM uses \f[V]CTRL_BREAK_EVENT\f[R] to perform thread dumps. -.IP \[bu] 2 -If the JVM is run as a service (for example, as a servlet engine for a -web server), then it can receive \f[V]CTRL_LOGOFF_EVENT\f[R] but -shouldn\[aq]t initiate shutdown because the operating system doesn\[aq]t -actually terminate the process. -To avoid possible interference such as this, the \f[V]-Xrs\f[R] option -can be used. -When the \f[V]-Xrs\f[R] option is used, the JVM doesn\[aq]t install a -console control handler, implying that it doesn\[aq]t watch for or -process \f[V]CTRL_C_EVENT\f[R], \f[V]CTRL_CLOSE_EVENT\f[R], -\f[V]CTRL_LOGOFF_EVENT\f[R], or \f[V]CTRL_SHUTDOWN_EVENT\f[R]. -.RE -.PP -There are two consequences of specifying \f[V]-Xrs\f[R]: -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] \f[V]SIGQUIT\f[R] thread dumps aren\[aq]t -available. -.IP \[bu] 2 -\f[B]Windows:\f[R] Ctrl + Break thread dumps aren\[aq]t available. -.PP -User code is responsible for causing shutdown hooks to run, for example, -by calling \f[V]System.exit()\f[R] when the JVM is to be terminated. -.RE -.TP -\f[V]-Xshare:\f[R]\f[I]mode\f[R] -Sets the class data sharing (CDS) mode. -.RS -.PP -Possible \f[I]mode\f[R] arguments for this option include the following: -.TP -\f[V]auto\f[R] -Use shared class data if possible (default). -.TP -\f[V]on\f[R] -Require using shared class data, otherwise fail. -.RS -.PP -\f[B]Note:\f[R] The \f[V]-Xshare:on\f[R] option is used for testing -purposes only. -It may cause the VM to unexpectedly exit during start-up when the CDS -archive cannot be used (for example, when certain VM parameters are -changed, or when a different JDK is used). -This option should not be used in production environments. -.RE -.TP -\f[V]off\f[R] -Do not attempt to use shared class data. -.RE -.TP -\f[V]-XshowSettings\f[R] -Shows all settings and then continues. -.TP -\f[V]-XshowSettings:\f[R]\f[I]category\f[R] -Shows settings and continues. -Possible \f[I]category\f[R] arguments for this option include the -following: -.RS -.TP -\f[V]all\f[R] -Shows all categories of settings in \f[B]verbose\f[R] detail. -.TP -\f[V]locale\f[R] -Shows settings related to locale. -.TP -\f[V]properties\f[R] -Shows settings related to system properties. -.TP -\f[V]security\f[R] -Shows all settings related to security. -.RS -.PP -sub-category arguments for \f[V]security\f[R] include the following: -.IP \[bu] 2 -\f[V]security:all\f[R] : shows all security settings -.IP \[bu] 2 -\f[V]security:properties\f[R] : shows security properties -.IP \[bu] 2 -\f[V]security:providers\f[R] : shows static security provider settings -.IP \[bu] 2 -\f[V]security:tls\f[R] : shows TLS related security settings -.RE -.TP -\f[V]vm\f[R] -Shows the settings of the JVM. -.TP -\f[V]system\f[R] -\f[B]Linux only:\f[R] Shows host system or container configuration and -continues. -.RE -.TP -\f[V]-Xss\f[R] \f[I]size\f[R] -Sets the thread stack size (in bytes). -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate KB, \f[V]m\f[R] -or \f[V]M\f[R] to indicate MB, or \f[V]g\f[R] or \f[V]G\f[R] to indicate -GB. -The actual size may be rounded up to a multiple of the system page size -as required by the operating system. -The default value depends on the platform. -For example: -.RS -.IP \[bu] 2 -Linux/x64: 1024 KB -.IP \[bu] 2 -Linux/Aarch64: 2048 KB -.IP \[bu] 2 -macOS/x64: 1024 KB -.IP \[bu] 2 -macOS/Aarch64: 2048 KB -.IP \[bu] 2 -Windows: The default value depends on virtual memory -.PP -The following examples set the thread stack size to 1024 KB in different -units: -.IP -.nf -\f[CB] --Xss1m --Xss1024k --Xss1048576 -\f[R] -.fi -.PP -This option is similar to \f[V]-XX:ThreadStackSize\f[R]. -.RE -.TP -\f[V]--add-reads\f[R] \f[I]module\f[R]\f[V]=\f[R]\f[I]target-module\f[R](\f[V],\f[R]\f[I]target-module\f[R])* -Updates \f[I]module\f[R] to read the \f[I]target-module\f[R], regardless -of the module declaration. -\f[I]target-module\f[R] can be \f[V]ALL-UNNAMED\f[R] to read all unnamed -modules. -.TP -\f[V]--add-exports\f[R] \f[I]module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]target-module\f[R](\f[V],\f[R]\f[I]target-module\f[R])* -Updates \f[I]module\f[R] to export \f[I]package\f[R] to -\f[I]target-module\f[R], regardless of module declaration. -\f[I]target-module\f[R] can be \f[V]ALL-UNNAMED\f[R] to export to all -unnamed modules. -.TP -\f[V]--add-opens\f[R] \f[I]module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]target-module\f[R](\f[V],\f[R]\f[I]target-module\f[R])* -Updates \f[I]module\f[R] to open \f[I]package\f[R] to -\f[I]target-module\f[R], regardless of module declaration. -.TP -\f[V]--limit-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...] -Specifies the limit of the universe of observable modules. -.TP -\f[V]--patch-module\f[R] \f[I]module\f[R]\f[V]=\f[R]\f[I]file\f[R](\f[V];\f[R]\f[I]file\f[R])* -Overrides or augments a module with classes and resources in JAR files -or directories. -.TP -\f[V]--source\f[R] \f[I]version\f[R] -Sets the version of the source in source-file mode. -.TP -\f[V]--sun-misc-unsafe-memory-access=\f[R] \f[I]value\f[R] -Allow or deny usage of unsupported API \f[V]sun.misc.Unsafe\f[R]. -\f[I]value\f[R] is one of: -.RS -.TP -\f[V]allow\f[R] -Allow use of the memory-access methods with no warnings at run time. -.TP -\f[V]warn\f[R] -Allow use of the memory-access methods, but issues a warning on the -first occasion that any memory-access method is used. -At most one warning is issued. -.TP -\f[V]debug\f[R] -Allow use of the memory-access methods, but issue a one-line warning and -a stack trace when any memory-access method is used. -.TP -\f[V]deny\f[R] -Disallow use of the memory-access methods by throwing an -\f[V]UnsupportedOperationException\f[R] on every usage. -.PP -The default value when the option is not specified is \f[V]allow\f[R]. -.RE -.SH EXTRA OPTIONS FOR MACOS -.PP -The following extra options are macOS specific. -.TP -\f[V]-XstartOnFirstThread\f[R] -Runs the \f[V]main()\f[R] method on the first (AppKit) thread. -.TP -\f[V]-Xdock:name=\f[R]\f[I]application_name\f[R] -Overrides the default application name displayed in dock. -.TP -\f[V]-Xdock:icon=\f[R]\f[I]path_to_icon_file\f[R] -Overrides the default icon displayed in dock. -.SH ADVANCED OPTIONS FOR JAVA -.PP -These \f[V]java\f[R] options can be used to enable other advanced -options. -.TP -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R] -Unlocks the options intended for diagnosing the JVM. -By default, this option is disabled and diagnostic options aren\[aq]t -available. -.RS -.PP -Command line options that are enabled with the use of this option are -not supported. -If you encounter issues while using any of these options, it is very -likely that you will be required to reproduce the problem without using -any of these unsupported options before Oracle Support can assist with -an investigation. -It is also possible that any of these options may be removed or their -behavior changed without any warning. -.RE -.TP -\f[V]-XX:+UnlockExperimentalVMOptions\f[R] -Unlocks the options that provide experimental features in the JVM. -By default, this option is disabled and experimental features aren\[aq]t -available. -.SH ADVANCED RUNTIME OPTIONS FOR JAVA -.PP -These \f[V]java\f[R] options control the runtime behavior of the Java -HotSpot VM. -.TP -\f[V]-XX:ActiveProcessorCount=\f[R]\f[I]x\f[R] -Overrides the number of CPUs that the VM will use to calculate the size -of thread pools it will use for various operations such as Garbage -Collection and ForkJoinPool. -.RS -.PP -The VM normally determines the number of available processors from the -operating system. -This flag can be useful for partitioning CPU resources when running -multiple Java processes in docker containers. -This flag is honored even if \f[V]UseContainerSupport\f[R] is not -enabled. -See \f[V]-XX:-UseContainerSupport\f[R] for a description of enabling and -disabling container support. -.RE -.TP -\f[V]-XX:AllocateHeapAt=\f[R]\f[I]path\f[R] -Takes a path to the file system and uses memory mapping to allocate the -object heap on the memory device. -Using this option enables the HotSpot VM to allocate the Java object -heap on an alternative memory device, such as an NV-DIMM, specified by -the user. -.RS -.PP -Alternative memory devices that have the same semantics as DRAM, -including the semantics of atomic operations, can be used instead of -DRAM for the object heap without changing the existing application code. -All other memory structures (such as the code heap, metaspace, and -thread stacks) continue to reside in DRAM. -.PP -Some operating systems expose non-DRAM memory through the file system. -Memory-mapped files in these file systems bypass the page cache and -provide a direct mapping of virtual memory to the physical memory on the -device. -The existing heap related flags (such as \f[V]-Xmx\f[R] and -\f[V]-Xms\f[R]) and garbage-collection related flags continue to work as -before. -.RE -.TP -\f[V]-XX:-CompactStrings\f[R] -Disables the Compact Strings feature. -By default, this option is enabled. -When this option is enabled, Java Strings containing only single-byte -characters are internally represented and stored as -single-byte-per-character Strings using ISO-8859-1 / Latin-1 encoding. -This reduces, by 50%, the amount of space required for Strings -containing only single-byte characters. -For Java Strings containing at least one multibyte character: these are -represented and stored as 2 bytes per character using UTF-16 encoding. -Disabling the Compact Strings feature forces the use of UTF-16 encoding -as the internal representation for all Java Strings. -.RS -.PP -Cases where it may be beneficial to disable Compact Strings include the -following: -.IP \[bu] 2 -When it\[aq]s known that an application overwhelmingly will be -allocating multibyte character Strings -.IP \[bu] 2 -In the unexpected event where a performance regression is observed in -migrating from Java SE 8 to Java SE 9 and an analysis shows that Compact -Strings introduces the regression -.PP -In both of these scenarios, disabling Compact Strings makes sense. -.RE -.TP -\f[V]-XX:ErrorFile=\f[R]\f[I]filename\f[R] -Specifies the path and file name to which error data is written when an -irrecoverable error occurs. -By default, this file is created in the current working directory and -named \f[V]hs_err_pid\f[R]\f[I]pid\f[R]\f[V].log\f[R] where -\f[I]pid\f[R] is the identifier of the process that encountered the -error. -.RS -.PP -The following example shows how to set the default log file (note that -the identifier of the process is specified as \f[V]%p\f[R]): -.RS -.PP -\f[V]-XX:ErrorFile=./hs_err_pid%p.log\f[R] -.RE -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] The following example shows how to set the error -log to \f[V]/var/log/java/java_error.log\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:ErrorFile=/var/log/java/java_error.log\f[R] -.RE -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] The following example shows how to set the error log -file to \f[V]C:/log/java/java_error.log\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:ErrorFile=C:/log/java/java_error.log\f[R] -.RE -.RE -.PP -If the file exists, and is writeable, then it will be overwritten. -Otherwise, if the file can\[aq]t be created in the specified directory -(due to insufficient space, permission problem, or another issue), then -the file is created in the temporary directory for the operating system: -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] The temporary directory is \f[V]/tmp\f[R]. -.IP \[bu] 2 -\f[B]Windows:\f[R] The temporary directory is specified by the value of -the \f[V]TMP\f[R] environment variable; if that environment variable -isn\[aq]t defined, then the value of the \f[V]TEMP\f[R] environment -variable is used. -.RE -.TP -\f[V]-XX:+ExtensiveErrorReports\f[R] -Enables the reporting of more extensive error information in the -\f[V]ErrorFile\f[R]. -This option can be turned on in environments where maximal information -is desired - even if the resulting logs may be quite large and/or -contain information that might be considered sensitive. -The information can vary from release to release, and across different -platforms. -By default this option is disabled. -.TP -\f[V]-XX:FlightRecorderOptions=\f[R]\f[I]parameter\f[R]\f[V]=\f[R]\f[I]value\f[R] (or) \f[V]-XX:FlightRecorderOptions:\f[R]\f[I]parameter\f[R]\f[V]=\f[R]\f[I]value\f[R] -Sets the parameters that control the behavior of JFR. -Multiple parameters can be specified by separating them with a comma. -.RS -.PP -The following list contains the available JFR -\f[I]parameter\f[R]\f[V]=\f[R]\f[I]value\f[R] entries: -.TP -\f[V]globalbuffersize=\f[R]\f[I]size\f[R] -Specifies the total amount of primary memory used for data retention. -The default value is based on the value specified for -\f[V]memorysize\f[R]. -Change the \f[V]memorysize\f[R] parameter to alter the size of global -buffers. -.TP -\f[V]maxchunksize=\f[R]\f[I]size\f[R] -Specifies the maximum size (in bytes) of the data chunks in a recording. -Append \f[V]m\f[R] or \f[V]M\f[R] to specify the size in megabytes (MB), -or \f[V]g\f[R] or \f[V]G\f[R] to specify the size in gigabytes (GB). -By default, the maximum size of data chunks is set to 12 MB. -The minimum allowed is 1 MB. -.TP -\f[V]memorysize=\f[R]\f[I]size\f[R] -Determines how much buffer memory should be used, and sets the -\f[V]globalbuffersize\f[R] and \f[V]numglobalbuffers\f[R] parameters -based on the size specified. -Append \f[V]m\f[R] or \f[V]M\f[R] to specify the size in megabytes (MB), -or \f[V]g\f[R] or \f[V]G\f[R] to specify the size in gigabytes (GB). -By default, the memory size is set to 10 MB. -.TP -\f[V]numglobalbuffers\f[R] -Specifies the number of global buffers used. -The default value is based on the memory size specified. -Change the \f[V]memorysize\f[R] parameter to alter the number of global -buffers. -.TP -\f[V]old-object-queue-size=number-of-objects\f[R] -Maximum number of old objects to track. -By default, the number of objects is set to 256. -.TP -\f[V]preserve-repository=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} -Specifies whether files stored in the disk repository should be kept -after the JVM has exited. -If false, files are deleted. -By default, this parameter is disabled. -.TP -\f[V]repository=\f[R]\f[I]path\f[R] -Specifies the repository (a directory) for temporary disk storage. -By default, the system\[aq]s temporary directory is used. -.TP -\f[V]retransform=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} -Specifies whether event classes should be retransformed using JVMTI. -If false, instrumentation is added when event classes are loaded. -By default, this parameter is enabled. -.TP -\f[V]stackdepth=\f[R]\f[I]depth\f[R] -Stack depth for stack traces. -By default, the depth is set to 64 method calls. -The maximum is 2048. -Values greater than 64 could create significant overhead and reduce -performance. -.TP -\f[V]threadbuffersize=\f[R]\f[I]size\f[R] -Specifies the per-thread local buffer size (in bytes). -By default, the local buffer size is set to 8 kilobytes, with a minimum -value of 4 kilobytes. -Overriding this parameter could reduce performance and is not -recommended. -.RE -.TP -\f[V]-XX:LargePageSizeInBytes=\f[R]\f[I]size\f[R] -Sets the maximum large page size (in bytes) used by the JVM. -The \f[I]size\f[R] argument must be a valid page size supported by the -environment to have any effect. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the size is set to 0, meaning that the JVM will use the -default large page size for the environment as the maximum size for -large pages. -See \f[B]Large Pages\f[R]. -.RS -.PP -The following example describes how to set the large page size to 1 -gigabyte (GB): -.RS -.PP -\f[V]-XX:LargePageSizeInBytes=1g\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxDirectMemorySize=\f[R]\f[I]size\f[R] -Sets the maximum total size (in bytes) of the \f[V]java.nio\f[R] -package, direct-buffer allocations. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -If not set, the flag is ignored and the JVM chooses the size for NIO -direct-buffer allocations automatically. -.RS -.PP -The following examples illustrate how to set the NIO size to 1024 KB in -different units: -.IP -.nf -\f[CB] --XX:MaxDirectMemorySize=1m --XX:MaxDirectMemorySize=1024k --XX:MaxDirectMemorySize=1048576 -\f[R] -.fi -.RE -.TP -\f[V]-XX:-MaxFDLimit\f[R] -Disables the attempt to set the soft limit for the number of open file -descriptors to the hard limit. -By default, this option is enabled on all platforms, but is ignored on -Windows. -The only time that you may need to disable this is on macOS, where its -use imposes a maximum of 10240, which is lower than the actual system -maximum. -.TP -\f[V]-XX:NativeMemoryTracking=\f[R]\f[I]mode\f[R] -Specifies the mode for tracking JVM native memory usage. -Possible \f[I]mode\f[R] arguments for this option include the following: -.RS -.TP -\f[V]off\f[R] -Instructs not to track JVM native memory usage. -This is the default behavior if you don\[aq]t specify the -\f[V]-XX:NativeMemoryTracking\f[R] option. -.TP -\f[V]summary\f[R] -Tracks memory usage only by JVM subsystems, such as Java heap, class, -code, and thread. -.TP -\f[V]detail\f[R] -In addition to tracking memory usage by JVM subsystems, track memory -usage by individual \f[V]CallSite\f[R], individual virtual memory region -and its committed regions. -.RE -.TP -\f[V]-XX:TrimNativeHeapInterval=\f[R]\f[I]millis\f[R] -Interval, in ms, at which the JVM will trim the native heap. -Lower values will reclaim memory more eagerly at the cost of higher -overhead. -A value of 0 (default) disables native heap trimming. -Native heap trimming is performed in a dedicated thread. -.RS -.PP -This option is only supported on Linux with GNU C Library (glibc). -.RE -.TP -\f[V]-XX:+NeverActAsServerClassMachine\f[R] -Enable the \[dq]Client VM emulation\[dq] mode which only uses the C1 JIT -compiler, a 32Mb CodeCache and the Serial GC. -The maximum amount of memory that the JVM may use (controlled by the -\f[V]-XX:MaxRAM=n\f[R] flag) is set to 1GB by default. -The string \[dq]emulated-client\[dq] is added to the JVM version string. -.RS -.PP -By default the flag is set to \f[V]true\f[R] only on Windows in 32-bit -mode and \f[V]false\f[R] in all other cases. -.PP -The \[dq]Client VM emulation\[dq] mode will not be enabled if any of the -following flags are used on the command line: -.IP -.nf -\f[CB] --XX:{+|-}TieredCompilation --XX:CompilationMode=mode --XX:TieredStopAtLevel=n --XX:{+|-}EnableJVMCI --XX:{+|-}UseJVMCICompiler -\f[R] -.fi -.RE -.TP -\f[V]-XX:ObjectAlignmentInBytes=\f[R]\f[I]alignment\f[R] -Sets the memory alignment of Java objects (in bytes). -By default, the value is set to 8 bytes. -The specified value should be a power of 2, and must be within the range -of 8 and 256 (inclusive). -This option makes it possible to use compressed pointers with large Java -heap sizes. -.RS -.PP -The heap size limit in bytes is calculated as: -.RS -.PP -\f[V]4GB * ObjectAlignmentInBytes\f[R] -.RE -.RS -.PP -\f[B]Note:\f[R] As the alignment value increases, the unused space -between objects also increases. -As a result, you may not realize any benefits from using compressed -pointers with large Java heap sizes. -.RE -.RE -.TP -\f[V]-XX:OnError=\f[R]\f[I]string\f[R] -Sets a custom command or a series of semicolon-separated commands to run -when an irrecoverable error occurs. -If the string contains spaces, then it must be enclosed in quotation -marks. -.RS -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] The following example shows how the -\f[V]-XX:OnError\f[R] option can be used to run the \f[V]gcore\f[R] -command to create a core image, and start the \f[V]gdb\f[R] debugger to -attach to the process in case of an irrecoverable error (the -\f[V]%p\f[R] designates the current process identifier): -.RS 2 -.RS -.PP -\f[V]-XX:OnError=\[dq]gcore %p;gdb -p %p\[dq]\f[R] -.RE -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] The following example shows how the -\f[V]-XX:OnError\f[R] option can be used to run the -\f[V]userdump.exe\f[R] utility to obtain a crash dump in case of an -irrecoverable error (the \f[V]%p\f[R] designates the current process -identifier). -This example assumes that the path to the \f[V]userdump.exe\f[R] utility -is specified in the \f[V]PATH\f[R] environment variable: -.RS 2 -.RS -.PP -\f[V]-XX:OnError=\[dq]userdump.exe %p\[dq]\f[R] -.RE -.RE -.RE -.TP -\f[V]-XX:OnOutOfMemoryError=\f[R]\f[I]string\f[R] -Sets a custom command or a series of semicolon-separated commands to run -when an \f[V]OutOfMemoryError\f[R] exception is first thrown. -If the string contains spaces, then it must be enclosed in quotation -marks. -For an example of a command string, see the description of the -\f[V]-XX:OnError\f[R] option. -.TP -\f[V]-XX:+PrintCommandLineFlags\f[R] -Enables printing of ergonomically selected JVM flags that appeared on -the command line. -It can be useful to know the ergonomic values set by the JVM, such as -the heap space size and the selected garbage collector. -By default, this option is disabled and flags aren\[aq]t printed. -.TP -\f[V]-XX:+PreserveFramePointer\f[R] -Selects between using the RBP register as a general purpose register -(\f[V]-XX:-PreserveFramePointer\f[R]) and using the RBP register to hold -the frame pointer of the currently executing method -(\f[V]-XX:+PreserveFramePointer\f[R] . -If the frame pointer is available, then external profiling tools (for -example, Linux perf) can construct more accurate stack traces. -.TP -\f[V]-XX:+PrintNMTStatistics\f[R] -Enables printing of collected native memory tracking data at JVM exit -when native memory tracking is enabled (see -\f[V]-XX:NativeMemoryTracking\f[R]). -By default, this option is disabled and native memory tracking data -isn\[aq]t printed. -.TP -\f[V]-XX:SharedArchiveFile=\f[R]\f[I]path\f[R] -Specifies the path and name of the class data sharing (CDS) archive file -.RS -.PP -See \f[B]Application Class Data Sharing\f[R]. -.RE -.TP -\f[V]-XX:+VerifySharedSpaces\f[R] -If this option is specified, the JVM will load a CDS archive file only -if it passes an integrity check based on CRC32 checksums. -The purpose of this flag is to check for unintentional damage to CDS -archive files in transmission or storage. -To guarantee the security and proper operation of CDS, the user must -ensure that the CDS archive files used by Java applications cannot be -modified without proper authorization. -.TP -\f[V]-XX:SharedArchiveConfigFile=\f[R]\f[I]shared_config_file\f[R] -Specifies additional shared data added to the archive file. -.TP -\f[V]-XX:SharedClassListFile=\f[R]\f[I]file_name\f[R] -Specifies the text file that contains the names of the classes to store -in the class data sharing (CDS) archive. -This file contains the full name of one class per line, except slashes -(\f[V]/\f[R]) replace dots (\f[V].\f[R]). -For example, to specify the classes \f[V]java.lang.Object\f[R] and -\f[V]hello.Main\f[R], create a text file that contains the following two -lines: -.RS -.IP -.nf -\f[CB] -java/lang/Object -hello/Main -\f[R] -.fi -.PP -The classes that you specify in this text file should include the -classes that are commonly used by the application. -They may include any classes from the application, extension, or -bootstrap class paths. -.PP -See \f[B]Application Class Data Sharing\f[R]. -.RE -.TP -\f[V]-XX:+ShowCodeDetailsInExceptionMessages\f[R] -Enables printing of improved \f[V]NullPointerException\f[R] messages. -When an application throws a \f[V]NullPointerException\f[R], the option -enables the JVM to analyze the program\[aq]s bytecode instructions to -determine precisely which reference is \f[V]null\f[R], and describes the -source with a null-detail message. -The null-detail message is calculated and returned by -\f[V]NullPointerException.getMessage()\f[R], and will be printed as the -exception message along with the method, filename, and line number. -By default, this option is enabled. -.TP -\f[V]-XX:+ShowMessageBoxOnError\f[R] -Enables the display of a dialog box when the JVM experiences an -irrecoverable error. -This prevents the JVM from exiting and keeps the process active so that -you can attach a debugger to it to investigate the cause of the error. -By default, this option is disabled. -.TP -\f[V]-XX:StartFlightRecording:\f[R]\f[I]parameter\f[R]\f[V]=\f[R]\f[I]value\f[R] -Starts a JFR recording for the Java application. -This option is equivalent to the \f[V]JFR.start\f[R] diagnostic command -that starts a recording during runtime. -\f[V]-XX:StartFlightRecording:help\f[R] prints available options and -example command lines. -You can set the following \f[I]parameter\f[R]\f[V]=\f[R]\f[I]value\f[R] -entries when starting a JFR recording: -.RS -.TP -\f[V]delay=\f[R]\f[I]time\f[R] -Specifies the delay between the Java application launch time and the -start of the recording. -Append \f[V]s\f[R] to specify the time in seconds, \f[V]m\f[R] for -minutes, \f[V]h\f[R] for hours, or \f[V]d\f[R] for days (for example, -specifying \f[V]10m\f[R] means 10 minutes). -By default, there\[aq]s no delay, and this parameter is set to 0. -.TP -\f[V]disk=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} -Specifies whether to write data to disk while recording. -By default, this parameter is enabled. -.TP -\f[V]dumponexit=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} -Specifies if the running recording is dumped when the JVM shuts down. -If enabled and a \f[V]filename\f[R] is not entered, the recording is -written to a file in the directory where the process was started. -The file name is a system-generated name that contains the process ID, -recording ID, and current timestamp, similar to -\f[V]hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr\f[R]. -By default, this parameter is disabled. -.TP -\f[V]duration=\f[R]\f[I]time\f[R] -Specifies the duration of the recording. -Append \f[V]s\f[R] to specify the time in seconds, \f[V]m\f[R] for -minutes, \f[V]h\f[R] for hours, or \f[V]d\f[R] for days (for example, -specifying \f[V]5h\f[R] means 5 hours). -By default, the duration isn\[aq]t limited, and this parameter is set to -0. -.TP -\f[V]filename=\f[R]\f[I]path\f[R] -Specifies the path and name of the file to which the recording is -written when the recording is stopped, for example: -.RS -.IP \[bu] 2 -\f[V]recording.jfr\f[R] -.IP \[bu] 2 -\f[V]/home/user/recordings/recording.jfr\f[R] -.IP \[bu] 2 -\f[V]c:\[rs]recordings\[rs]recording.jfr\f[R] -.PP -If %p and/or %t is specified in the filename, it expands to the -JVM\[aq]s PID and the current timestamp, respectively. -The filename may also be a directory in which case, the filename is -generated from the PID and the current date in the specified directory. -.RE -.TP -\f[V]name=\f[R]\f[I]identifier\f[R] -Takes both the name and the identifier of a recording. -.TP -\f[V]maxage=\f[R]\f[I]time\f[R] -Specifies the maximum age of disk data to keep for the recording. -This parameter is valid only when the \f[V]disk\f[R] parameter is set to -\f[V]true\f[R]. -Append \f[V]s\f[R] to specify the time in seconds, \f[V]m\f[R] for -minutes, \f[V]h\f[R] for hours, or \f[V]d\f[R] for days (for example, -specifying \f[V]30s\f[R] means 30 seconds). -By default, the maximum age isn\[aq]t limited, and this parameter is set -to \f[V]0s\f[R]. -.TP -\f[V]maxsize=\f[R]\f[I]size\f[R] -Specifies the maximum size (in bytes) of disk data to keep for the -recording. -This parameter is valid only when the \f[V]disk\f[R] parameter is set to -\f[V]true\f[R]. -The value must not be less than the value for the \f[V]maxchunksize\f[R] -parameter set with \f[V]-XX:FlightRecorderOptions\f[R]. -Append \f[V]m\f[R] or \f[V]M\f[R] to specify the size in megabytes, or -\f[V]g\f[R] or \f[V]G\f[R] to specify the size in gigabytes. -By default, the maximum size of disk data isn\[aq]t limited, and this -parameter is set to \f[V]0\f[R]. -.TP -\f[V]path-to-gc-roots=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} -Specifies whether to collect the path to garbage collection (GC) roots -at the end of a recording. -By default, this parameter is disabled. -.RS -.PP -The path to GC roots is useful for finding memory leaks, but collecting -it is time-consuming. -Enable this option only when you start a recording for an application -that you suspect has a memory leak. -If the \f[V]settings\f[R] parameter is set to \f[V]profile\f[R], the -stack trace from where the potential leaking object was allocated is -included in the information collected. -.RE -.TP -\f[V]settings=\f[R]\f[I]path\f[R] -Specifies the path and name of the event settings file (of type JFC). -By default, the \f[V]default.jfc\f[R] file is used, which is located in -\f[V]JAVA_HOME/lib/jfr\f[R]. -This default settings file collects a predefined set of information with -low overhead, so it has minimal impact on performance and can be used -with recordings that run continuously. -.RS -.PP -A second settings file is also provided, profile.jfc, which provides -more data than the default configuration, but can have more overhead and -impact performance. -Use this configuration for short periods of time when more information -is needed. -.RE -.PP -You can specify values for multiple parameters by separating them with a -comma. -Event settings and .jfc options can be specified using the following -syntax: -.TP -\f[V]option=\f[R]\f[I]value\f[R] -Specifies the option value to modify. -To list available options, use the \f[V]JAVA_HOME\f[R]/bin/jfr tool. -.TP -\f[V]event-setting=\f[R]\f[I]value\f[R] -Specifies the event setting value to modify. -Use the form: \f[V]#=\f[R]. -To add a new event setting, prefix the event name with \[aq]+\[aq]. -.PP -You can specify values for multiple event settings and .jfc options by -separating them with a comma. -In case of a conflict between a parameter and a .jfc option, the -parameter will take precedence. -The whitespace delimiter can be omitted for timespan values, i.e. -20ms. -For more information about the settings syntax, see Javadoc of the -jdk.jfr package. -.PP -To only see warnings and errors from JFR during startup set --Xlog:jfr+startup=warning. -.RE -.TP -\f[V]-XX:ThreadStackSize=\f[R]\f[I]size\f[R] -Sets the Java thread stack size (in kilobytes). -Use of a scaling suffix, such as \f[V]k\f[R], results in the scaling of -the kilobytes value so that \f[V]-XX:ThreadStackSize=1k\f[R] sets the -Java thread stack size to 1024*1024 bytes or 1 megabyte. -The default value depends on the platform. -For example: -.RS -.IP \[bu] 2 -Linux/x64: 1024 KB -.IP \[bu] 2 -Linux/Aarch64: 2048 KB -.IP \[bu] 2 -macOS/x64: 1024 KB -.IP \[bu] 2 -macOS/Aarch64: 2048 KB -.IP \[bu] 2 -Windows: The default value depends on virtual memory -.PP -The following examples show how to set the thread stack size to 1 -megabyte in different units: -.IP -.nf -\f[CB] --XX:ThreadStackSize=1k --XX:ThreadStackSize=1024 -\f[R] -.fi -.PP -This option is similar to \f[V]-Xss\f[R]. -.RE -.TP -\f[V]-XX:-UseCompressedOops\f[R] -Disables the use of compressed pointers. -By default, this option is enabled, and compressed pointers are used. -This will automatically limit the maximum ergonomically determined Java -heap size to the maximum amount of memory that can be covered by -compressed pointers. -By default this range is 32 GB. -.RS -.PP -With compressed oops enabled, object references are represented as -32-bit offsets instead of 64-bit pointers, which typically increases -performance when running the application with Java heap sizes smaller -than the compressed oops pointer range. -This option works only for 64-bit JVMs. -.PP -It\[aq]s possible to use compressed pointers with Java heap sizes -greater than 32 GB. -See the \f[V]-XX:ObjectAlignmentInBytes\f[R] option. -.RE -.TP -\f[V]-XX:-UseContainerSupport\f[R] -\f[B]Linux only:\f[R] The VM now provides automatic container detection -support, which allows the VM to determine the amount of memory and -number of processors that are available to a Java process running in -docker containers. -It uses this information to allocate system resources. -The default for this flag is \f[V]true\f[R], and container support is -enabled by default. -It can be disabled with \f[V]-XX:-UseContainerSupport\f[R]. -.RS -.PP -Unified Logging is available to help to diagnose issues related to this -support. -.PP -Use \f[V]-Xlog:os+container=trace\f[R] for maximum logging of container -information. -See \f[B]Enable Logging with the JVM Unified Logging Framework\f[R] for -a description of using Unified Logging. -.RE -.TP -\f[V]-XX:+UseLargePages\f[R] -Enables the use of large page memory. -By default, this option is disabled and large page memory isn\[aq]t -used. -.RS -.PP -See \f[B]Large Pages\f[R]. -.RE -.TP -\f[V]-XX:+UseTransparentHugePages\f[R] -\f[B]Linux only:\f[R] Enables the use of large pages that can -dynamically grow or shrink. -This option is disabled by default. -You may encounter performance problems with transparent huge pages as -the OS moves other pages around to create huge pages; this option is -made available for experimentation. -.TP -\f[V]-XX:+AllowUserSignalHandlers\f[R] -\f[B]Non-Windows:\f[R] Enables installation of signal handlers by the -application. -By default, this option is disabled and the application isn\[aq]t -allowed to install signal handlers. -.TP -\f[V]-XX:VMOptionsFile=\f[R]\f[I]filename\f[R] -Allows user to specify VM options in a file, for example, -\f[V]java -XX:VMOptionsFile=/var/my_vm_options HelloWorld\f[R]. -.TP -\f[V]-XX:UseBranchProtection=\f[R]\f[I]mode\f[R] -\f[B]Linux AArch64 only:\f[R] Specifies the branch protection mode. -All options other than \f[V]none\f[R] require the VM to have been built -with branch protection enabled. -In addition, for full protection, any native libraries provided by -applications should be compiled with the same level of protection. -.RS -.PP -Possible \f[I]mode\f[R] arguments for this option include the following: -.TP -\f[V]none\f[R] -Do not use branch protection. -This is the default value. -.TP -\f[V]standard\f[R] -Enables all branch protection modes available on the current platform. -.TP -\f[V]pac-ret\f[R] -Enables protection against ROP based attacks. -(AArch64 8.3+ only) -.RE -.SH ADVANCED JIT COMPILER OPTIONS FOR JAVA -.PP -These \f[V]java\f[R] options control the dynamic just-in-time (JIT) -compilation performed by the Java HotSpot VM. -.TP -\f[V]-XX:AllocateInstancePrefetchLines=\f[R]\f[I]lines\f[R] -Sets the number of lines to prefetch ahead of the instance allocation -pointer. -By default, the number of lines to prefetch is set to 1: -.RS -.RS -.PP -\f[V]-XX:AllocateInstancePrefetchLines=1\f[R] -.RE -.RE -.TP -\f[V]-XX:AllocatePrefetchDistance=\f[R]\f[I]size\f[R] -Sets the size (in bytes) of the prefetch distance for object allocation. -Memory about to be written with the value of new objects is prefetched -up to this distance starting from the address of the last allocated -object. -Each Java thread has its own allocation point. -.RS -.PP -Negative values denote that prefetch distance is chosen based on the -platform. -Positive values are bytes to prefetch. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value is set to -1. -.PP -The following example shows how to set the prefetch distance to 1024 -bytes: -.RS -.PP -\f[V]-XX:AllocatePrefetchDistance=1024\f[R] -.RE -.RE -.TP -\f[V]-XX:AllocatePrefetchInstr=\f[R]\f[I]instruction\f[R] -Sets the prefetch instruction to prefetch ahead of the allocation -pointer. -Possible values are from 0 to 3. -The actual instructions behind the values depend on the platform. -By default, the prefetch instruction is set to 0: -.RS -.RS -.PP -\f[V]-XX:AllocatePrefetchInstr=0\f[R] -.RE -.RE -.TP -\f[V]-XX:AllocatePrefetchLines=\f[R]\f[I]lines\f[R] -Sets the number of cache lines to load after the last object allocation -by using the prefetch instructions generated in compiled code. -The default value is 1 if the last allocated object was an instance, and -3 if it was an array. -.RS -.PP -The following example shows how to set the number of loaded cache lines -to 5: -.RS -.PP -\f[V]-XX:AllocatePrefetchLines=5\f[R] -.RE -.RE -.TP -\f[V]-XX:AllocatePrefetchStepSize=\f[R]\f[I]size\f[R] -Sets the step size (in bytes) for sequential prefetch instructions. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the step size is set to 16 bytes: -.RS -.RS -.PP -\f[V]-XX:AllocatePrefetchStepSize=16\f[R] -.RE -.RE -.TP -\f[V]-XX:AllocatePrefetchStyle=\f[R]\f[I]style\f[R] -Sets the generated code style for prefetch instructions. -The \f[I]style\f[R] argument is an integer from 0 to 3: -.RS -.TP -\f[V]0\f[R] -Don\[aq]t generate prefetch instructions. -.TP -\f[V]1\f[R] -Execute prefetch instructions after each allocation. -This is the default setting. -.TP -\f[V]2\f[R] -Use the thread-local allocation block (TLAB) watermark pointer to -determine when prefetch instructions are executed. -.TP -\f[V]3\f[R] -Generate one prefetch instruction per cache line. -.RE -.TP -\f[V]-XX:+BackgroundCompilation\f[R] -Enables background compilation. -This option is enabled by default. -To disable background compilation, specify -\f[V]-XX:-BackgroundCompilation\f[R] (this is equivalent to specifying -\f[V]-Xbatch\f[R]). -.TP -\f[V]-XX:CICompilerCount=\f[R]\f[I]threads\f[R] -Sets the number of compiler threads to use for compilation. -By default, the number of compiler threads is selected automatically -depending on the number of CPUs and memory available for compiled code. -The following example shows how to set the number of threads to 2: -.RS -.RS -.PP -\f[V]-XX:CICompilerCount=2\f[R] -.RE -.RE -.TP -\f[V]-XX:+UseDynamicNumberOfCompilerThreads\f[R] -Dynamically create compiler thread up to the limit specified by -\f[V]-XX:CICompilerCount\f[R]. -This option is enabled by default. -.TP -\f[V]-XX:CompileCommand=\f[R]\f[I]command\f[R]\f[V],\f[R]\f[I]method\f[R][\f[V],\f[R]\f[I]option\f[R]] -Specifies a \f[I]command\f[R] to perform on a \f[I]method\f[R]. -For example, to exclude the \f[V]indexOf()\f[R] method of the -\f[V]String\f[R] class from being compiled, use the following: -.RS -.RS -.PP -\f[V]-XX:CompileCommand=exclude,java/lang/String.indexOf\f[R] -.RE -.PP -Note that the full class name is specified, including all packages and -subpackages separated by a slash (\f[V]/\f[R]). -For easier cut-and-paste operations, it\[aq]s also possible to use the -method name format produced by the \f[V]-XX:+PrintCompilation\f[R] and -\f[V]-XX:+LogCompilation\f[R] options: -.RS -.PP -\f[V]-XX:CompileCommand=exclude,java.lang.String::indexOf\f[R] -.RE -.PP -If the method is specified without the signature, then the command is -applied to all methods with the specified name. -However, you can also specify the signature of the method in the class -file format. -In this case, you should enclose the arguments in quotation marks, -because otherwise the shell treats the semicolon as a command end. -For example, if you want to exclude only the \f[V]indexOf(String)\f[R] -method of the \f[V]String\f[R] class from being compiled, use the -following: -.RS -.PP -\f[V]-XX:CompileCommand=\[dq]exclude,java/lang/String.indexOf,(Ljava/lang/String;)I\[dq]\f[R] -.RE -.PP -You can also use the asterisk (*) as a wildcard for class and method -names. -For example, to exclude all \f[V]indexOf()\f[R] methods in all classes -from being compiled, use the following: -.RS -.PP -\f[V]-XX:CompileCommand=exclude,*.indexOf\f[R] -.RE -.PP -The commas and periods are aliases for spaces, making it easier to pass -compiler commands through a shell. -You can pass arguments to \f[V]-XX:CompileCommand\f[R] using spaces as -separators by enclosing the argument in quotation marks: -.RS -.PP -\f[V]-XX:CompileCommand=\[dq]exclude java/lang/String indexOf\[dq]\f[R] -.RE -.PP -Note that after parsing the commands passed on the command line using -the \f[V]-XX:CompileCommand\f[R] options, the JIT compiler then reads -commands from the \f[V].hotspot_compiler\f[R] file. -You can add commands to this file or specify a different file using the -\f[V]-XX:CompileCommandFile\f[R] option. -.PP -To add several commands, either specify the \f[V]-XX:CompileCommand\f[R] -option multiple times, or separate each argument with the new line -separator (\f[V]\[rs]n\f[R]). -The following commands are available: -.TP -\f[V]break\f[R] -Sets a breakpoint when debugging the JVM to stop at the beginning of -compilation of the specified method. -.TP -\f[V]compileonly\f[R] -Excludes all methods from compilation except for the specified method. -As an alternative, you can use the \f[V]-XX:CompileOnly\f[R] option, -which lets you specify several methods. -.TP -\f[V]dontinline\f[R] -Prevents inlining of the specified method. -.TP -\f[V]exclude\f[R] -Excludes the specified method from compilation. -.TP -\f[V]help\f[R] -Prints a help message for the \f[V]-XX:CompileCommand\f[R] option. -.TP -\f[V]inline\f[R] -Attempts to inline the specified method. -.TP -\f[V]log\f[R] -Excludes compilation logging (with the \f[V]-XX:+LogCompilation\f[R] -option) for all methods except for the specified method. -By default, logging is performed for all compiled methods. -.TP -\f[V]option\f[R] -Passes a JIT compilation option to the specified method in place of the -last argument (\f[V]option\f[R]). -The compilation option is set at the end, after the method name. -For example, to enable the \f[V]BlockLayoutByFrequency\f[R] option for -the \f[V]append()\f[R] method of the \f[V]StringBuffer\f[R] class, use -the following: -.RS -.RS -.PP -\f[V]-XX:CompileCommand=option,java/lang/StringBuffer.append,BlockLayoutByFrequency\f[R] -.RE -.PP -You can specify multiple compilation options, separated by commas or -spaces. -.RE -.TP -\f[V]print\f[R] -Prints generated assembler code after compilation of the specified -method. -.TP -\f[V]quiet\f[R] -Instructs not to print the compile commands. -By default, the commands that you specify with the -\f[V]-XX:CompileCommand\f[R] option are printed; for example, if you -exclude from compilation the \f[V]indexOf()\f[R] method of the -\f[V]String\f[R] class, then the following is printed to standard -output: -.RS -.RS -.PP -\f[V]CompilerOracle: exclude java/lang/String.indexOf\f[R] -.RE -.PP -You can suppress this by specifying the -\f[V]-XX:CompileCommand=quiet\f[R] option before other -\f[V]-XX:CompileCommand\f[R] options. -.RE -.RE -.TP -\f[V]-XX:CompileCommandFile=\f[R]\f[I]filename\f[R] -Sets the file from which JIT compiler commands are read. -By default, the \f[V].hotspot_compiler\f[R] file is used to store -commands performed by the JIT compiler. -.RS -.PP -Each line in the command file represents a command, a class name, and a -method name for which the command is used. -For example, this line prints assembly code for the \f[V]toString()\f[R] -method of the \f[V]String\f[R] class: -.RS -.PP -\f[V]print java/lang/String toString\f[R] -.RE -.PP -If you\[aq]re using commands for the JIT compiler to perform on methods, -then see the \f[V]-XX:CompileCommand\f[R] option. -.RE -.TP -\f[V]-XX:CompilerDirectivesFile=\f[R]\f[I]file\f[R] -Adds directives from a file to the directives stack when a program -starts. -See \f[B]Compiler Control\f[R] -[https://docs.oracle.com/en/java/javase/12/vm/compiler-control1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A]. -.RS -.PP -The \f[V]-XX:CompilerDirectivesFile\f[R] option has to be used together -with the \f[V]-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks -diagnostic JVM options. -.RE -.TP -\f[V]-XX:+CompilerDirectivesPrint\f[R] -Prints the directives stack when the program starts or when a new -directive is added. -.RS -.PP -The \f[V]-XX:+CompilerDirectivesPrint\f[R] option has to be used -together with the \f[V]-XX:UnlockDiagnosticVMOptions\f[R] option that -unlocks diagnostic JVM options. -.RE -.TP -\f[V]-XX:CompileOnly=\f[R]\f[I]methods\f[R] -Sets the list of methods (separated by commas) to which compilation -should be restricted. -Only the specified methods are compiled. -.RS -.PP -\f[V]-XX:CompileOnly=method1,method2,...,methodN\f[R] is an alias for: -.IP -.nf -\f[CB] --XX:CompileCommand=compileonly,method1 --XX:CompileCommand=compileonly,method2 -\&... --XX:CompileCommand=compileonly,methodN -\f[R] -.fi -.RE -.TP -\f[V]-XX:CompileThresholdScaling=\f[R]\f[I]scale\f[R] -Provides unified control of first compilation. -This option controls when methods are first compiled for both the tiered -and the nontiered modes of operation. -The \f[V]CompileThresholdScaling\f[R] option has a floating point value -between 0 and +Inf and scales the thresholds corresponding to the -current mode of operation (both tiered and nontiered). -Setting \f[V]CompileThresholdScaling\f[R] to a value less than 1.0 -results in earlier compilation while values greater than 1.0 delay -compilation. -Setting \f[V]CompileThresholdScaling\f[R] to 0 is equivalent to -disabling compilation. -.TP -\f[V]-XX:+DoEscapeAnalysis\f[R] -Enables the use of escape analysis. -This option is enabled by default. -To disable the use of escape analysis, specify -\f[V]-XX:-DoEscapeAnalysis\f[R]. -.TP -\f[V]-XX:InitialCodeCacheSize=\f[R]\f[I]size\f[R] -Sets the initial code cache size (in bytes). -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value depends on the platform. -The initial code cache size shouldn\[aq]t be less than the system\[aq]s -minimal memory page size. -The following example shows how to set the initial code cache size to 32 -KB: -.RS -.RS -.PP -\f[V]-XX:InitialCodeCacheSize=32k\f[R] -.RE -.RE -.TP -\f[V]-XX:+Inline\f[R] -Enables method inlining. -This option is enabled by default to increase performance. -To disable method inlining, specify \f[V]-XX:-Inline\f[R]. -.TP -\f[V]-XX:InlineSmallCode=\f[R]\f[I]size\f[R] -Sets the maximum code size (in bytes) for already compiled methods that -may be inlined. -This flag only applies to the C2 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value depends on the platform and on whether tiered -compilation is enabled. -In the following example it is set to 1000 bytes: -.RS -.RS -.PP -\f[V]-XX:InlineSmallCode=1000\f[R] -.RE -.RE -.TP -\f[V]-XX:+LogCompilation\f[R] -Enables logging of compilation activity to a file named -\f[V]hotspot.log\f[R] in the current working directory. -You can specify a different log file path and name using the -\f[V]-XX:LogFile\f[R] option. -.RS -.PP -By default, this option is disabled and compilation activity isn\[aq]t -logged. -The \f[V]-XX:+LogCompilation\f[R] option has to be used together with -the \f[V]-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks -diagnostic JVM options. -.PP -You can enable verbose diagnostic output with a message printed to the -console every time a method is compiled by using the -\f[V]-XX:+PrintCompilation\f[R] option. -.RE -.TP -\f[V]-XX:FreqInlineSize=\f[R]\f[I]size\f[R] -Sets the maximum bytecode size (in bytes) of a hot method to be inlined. -This flag only applies to the C2 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value depends on the platform. -In the following example it is set to 325 bytes: -.RS -.RS -.PP -\f[V]-XX:FreqInlineSize=325\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxInlineSize=\f[R]\f[I]size\f[R] -Sets the maximum bytecode size (in bytes) of a cold method to be -inlined. -This flag only applies to the C2 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the maximum bytecode size is set to 35 bytes: -.RS -.RS -.PP -\f[V]-XX:MaxInlineSize=35\f[R] -.RE -.RE -.TP -\f[V]-XX:C1MaxInlineSize=\f[R]\f[I]size\f[R] -Sets the maximum bytecode size (in bytes) of a cold method to be -inlined. -This flag only applies to the C1 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the maximum bytecode size is set to 35 bytes: -.RS -.RS -.PP -\f[V]-XX:MaxInlineSize=35\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxTrivialSize=\f[R]\f[I]size\f[R] -Sets the maximum bytecode size (in bytes) of a trivial method to be -inlined. -This flag only applies to the C2 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the maximum bytecode size of a trivial method is set to 6 -bytes: -.RS -.RS -.PP -\f[V]-XX:MaxTrivialSize=6\f[R] -.RE -.RE -.TP -\f[V]-XX:C1MaxTrivialSize=\f[R]\f[I]size\f[R] -Sets the maximum bytecode size (in bytes) of a trivial method to be -inlined. -This flag only applies to the C1 compiler. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -By default, the maximum bytecode size of a trivial method is set to 6 -bytes: -.RS -.RS -.PP -\f[V]-XX:MaxTrivialSize=6\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxNodeLimit=\f[R]\f[I]nodes\f[R] -Sets the maximum number of nodes to be used during single method -compilation. -By default the value depends on the features enabled. -In the following example the maximum number of nodes is set to 100,000: -.RS -.RS -.PP -\f[V]-XX:MaxNodeLimit=100000\f[R] -.RE -.RE -.TP -\f[V]-XX:NonNMethodCodeHeapSize=\f[R]\f[I]size\f[R] -Sets the size in bytes of the code segment containing nonmethod code. -.RS -.PP -A nonmethod code segment containing nonmethod code, such as compiler -buffers and the bytecode interpreter. -This code type stays in the code cache forever. -This flag is used only if \f[V]-XX:SegmentedCodeCache\f[R] is enabled. -.RE -.TP -\f[V]-XX:NonProfiledCodeHeapSize=\f[R]\f[I]size\f[R] -Sets the size in bytes of the code segment containing nonprofiled -methods. -This flag is used only if \f[V]-XX:SegmentedCodeCache\f[R] is enabled. -.TP -\f[V]-XX:+OptimizeStringConcat\f[R] -Enables the optimization of \f[V]String\f[R] concatenation operations. -This option is enabled by default. -To disable the optimization of \f[V]String\f[R] concatenation -operations, specify \f[V]-XX:-OptimizeStringConcat\f[R]. -.TP -\f[V]-XX:+PrintAssembly\f[R] -Enables printing of assembly code for bytecoded and native methods by -using the external \f[V]hsdis-.so\f[R] or \f[V].dll\f[R] library. -For 64-bit VM on Windows, it\[aq]s \f[V]hsdis-amd64.dll\f[R]. -This lets you to see the generated code, which may help you to diagnose -performance issues. -.RS -.PP -By default, this option is disabled and assembly code isn\[aq]t printed. -The \f[V]-XX:+PrintAssembly\f[R] option has to be used together with the -\f[V]-XX:UnlockDiagnosticVMOptions\f[R] option that unlocks diagnostic -JVM options. -.RE -.TP -\f[V]-XX:ProfiledCodeHeapSize=\f[R]\f[I]size\f[R] -Sets the size in bytes of the code segment containing profiled methods. -This flag is used only if \f[V]-XX:SegmentedCodeCache\f[R] is enabled. -.TP -\f[V]-XX:+PrintCompilation\f[R] -Enables verbose diagnostic output from the JVM by printing a message to -the console every time a method is compiled. -This lets you to see which methods actually get compiled. -By default, this option is disabled and diagnostic output isn\[aq]t -printed. -.RS -.PP -You can also log compilation activity to a file by using the -\f[V]-XX:+LogCompilation\f[R] option. -.RE -.TP -\f[V]-XX:+PrintInlining\f[R] -Enables printing of inlining decisions. -This let\[aq]s you see which methods are getting inlined. -.RS -.PP -By default, this option is disabled and inlining information isn\[aq]t -printed. -The \f[V]-XX:+PrintInlining\f[R] option has to be used together with the -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R] option that unlocks diagnostic -JVM options. -.RE -.TP -\f[V]-XX:ReservedCodeCacheSize=\f[R]\f[I]size\f[R] -Sets the maximum code cache size (in bytes) for JIT-compiled code. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default maximum code cache size is 240 MB; if you disable tiered -compilation with the option \f[V]-XX:-TieredCompilation\f[R], then the -default size is 48 MB. -This option has a limit of 2 GB; otherwise, an error is generated. -The maximum code cache size shouldn\[aq]t be less than the initial code -cache size; see the option \f[V]-XX:InitialCodeCacheSize\f[R]. -.TP -\f[V]-XX:+SegmentedCodeCache\f[R] -Enables segmentation of the code cache, without which the code cache -consists of one large segment. -With \f[V]-XX:+SegmentedCodeCache\f[R], separate segments will be used -for non-method, profiled method, and non-profiled method code. -The segments are not resized at runtime. -The advantages are better control of the memory footprint, reduced code -fragmentation, and better CPU iTLB (instruction translation lookaside -buffer) and instruction cache behavior due to improved locality. -.RS -.PP -The feature is enabled by default if tiered compilation is enabled -(\f[V]-XX:+TieredCompilation\f[R] ) and the reserved code cache size -(\f[V]-XX:ReservedCodeCacheSize\f[R]) is at least 240 MB. -.RE -.TP -\f[V]-XX:StartAggressiveSweepingAt=\f[R]\f[I]percent\f[R] -Forces stack scanning of active methods to aggressively remove unused -code when only the given percentage of the code cache is free. -The default value is 10%. -.TP -\f[V]-XX:-TieredCompilation\f[R] -Disables the use of tiered compilation. -By default, this option is enabled. -.TP -\f[V]-XX:UseSSE=\f[R]\f[I]version\f[R] -Enables the use of SSE instruction set of a specified version. -Is set by default to the highest supported version available (x86 only). -.TP -\f[V]-XX:UseAVX=\f[R]\f[I]version\f[R] -Enables the use of AVX instruction set of a specified version. -Is set by default to the highest supported version available (x86 only). -.TP -\f[V]-XX:+UseAES\f[R] -Enables hardware-based AES intrinsics for hardware that supports it. -This option is on by default on hardware that has the necessary -instructions. -The \f[V]-XX:+UseAES\f[R] is used in conjunction with -\f[V]UseAESIntrinsics\f[R]. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseAESIntrinsics\f[R] -Enables AES intrinsics. -Specifying \f[V]-XX:+UseAESIntrinsics\f[R] is equivalent to also -enabling \f[V]-XX:+UseAES\f[R]. -To disable hardware-based AES intrinsics, specify -\f[V]-XX:-UseAES -XX:-UseAESIntrinsics\f[R]. -For example, to enable hardware AES, use the following flags: -.RS -.RS -.PP -\f[V]-XX:+UseAES -XX:+UseAESIntrinsics\f[R] -.RE -.PP -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.RE -.TP -\f[V]-XX:+UseAESCTRIntrinsics\f[R] -Analogous to \f[V]-XX:+UseAESIntrinsics\f[R] enables AES/CTR intrinsics. -.TP -\f[V]-XX:+UseGHASHIntrinsics\f[R] -Controls the use of GHASH intrinsics. -Enabled by default on platforms that support the corresponding -instructions. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseChaCha20Intrinsics\f[R] -Enable ChaCha20 intrinsics. -This option is on by default for supported platforms. -To disable ChaCha20 intrinsics, specify -\f[V]-XX:-UseChaCha20Intrinsics\f[R]. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UsePoly1305Intrinsics\f[R] -Enable Poly1305 intrinsics. -This option is on by default for supported platforms. -To disable Poly1305 intrinsics, specify -\f[V]-XX:-UsePoly1305Intrinsics\f[R]. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseBASE64Intrinsics\f[R] -Controls the use of accelerated BASE64 encoding routines for -\f[V]java.util.Base64\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseAdler32Intrinsics\f[R] -Controls the use of Adler32 checksum algorithm intrinsic for -\f[V]java.util.zip.Adler32\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseCRC32Intrinsics\f[R] -Controls the use of CRC32 intrinsics for \f[V]java.util.zip.CRC32\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseCRC32CIntrinsics\f[R] -Controls the use of CRC32C intrinsics for -\f[V]java.util.zip.CRC32C\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseSHA\f[R] -Enables hardware-based intrinsics for SHA crypto hash functions for some -hardware. -The \f[V]UseSHA\f[R] option is used in conjunction with the -\f[V]UseSHA1Intrinsics\f[R], \f[V]UseSHA256Intrinsics\f[R], and -\f[V]UseSHA512Intrinsics\f[R] options. -.RS -.PP -The \f[V]UseSHA\f[R] and \f[V]UseSHA*Intrinsics\f[R] flags are enabled -by default on machines that support the corresponding instructions. -.PP -This feature is applicable only when using the -\f[V]sun.security.provider.Sun\f[R] provider for SHA operations. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.PP -To disable all hardware-based SHA intrinsics, specify the -\f[V]-XX:-UseSHA\f[R]. -To disable only a particular SHA intrinsic, use the appropriate -corresponding option. -For example: \f[V]-XX:-UseSHA256Intrinsics\f[R]. -.RE -.TP -\f[V]-XX:+UseSHA1Intrinsics\f[R] -Enables intrinsics for SHA-1 crypto hash function. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseSHA256Intrinsics\f[R] -Enables intrinsics for SHA-224 and SHA-256 crypto hash functions. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseSHA512Intrinsics\f[R] -Enables intrinsics for SHA-384 and SHA-512 crypto hash functions. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseMathExactIntrinsics\f[R] -Enables intrinsification of various \f[V]java.lang.Math.*Exact()\f[R] -functions. -Enabled by default. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseMultiplyToLenIntrinsic\f[R] -Enables intrinsification of \f[V]BigInteger.multiplyToLen()\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP --XX:+UseSquareToLenIntrinsic -Enables intrinsification of \f[V]BigInteger.squareToLen()\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP --XX:+UseMulAddIntrinsic -Enables intrinsification of \f[V]BigInteger.mulAdd()\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP --XX:+UseMontgomeryMultiplyIntrinsic -Enables intrinsification of \f[V]BigInteger.montgomeryMultiply()\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP --XX:+UseMontgomerySquareIntrinsic -Enables intrinsification of \f[V]BigInteger.montgomerySquare()\f[R]. -Enabled by default on platforms that support it. -Flags that control intrinsics now require the option -\f[V]-XX:+UnlockDiagnosticVMOptions\f[R]. -.TP -\f[V]-XX:+UseCMoveUnconditionally\f[R] -Generates CMove (scalar and vector) instructions regardless of -profitability analysis. -.TP -\f[V]-XX:+UseCodeCacheFlushing\f[R] -Enables flushing of the code cache before shutting down the compiler. -This option is enabled by default. -To disable flushing of the code cache before shutting down the compiler, -specify \f[V]-XX:-UseCodeCacheFlushing\f[R]. -.TP -\f[V]-XX:+UseCondCardMark\f[R] -Enables checking if the card is already marked before updating the card -table. -This option is disabled by default. -It should be used only on machines with multiple sockets, where it -increases the performance of Java applications that rely on concurrent -operations. -.TP -\f[V]-XX:+UseCountedLoopSafepoints\f[R] -Keeps safepoints in counted loops. -Its default value depends on whether the selected garbage collector -requires low latency safepoints. -.TP -\f[V]-XX:LoopStripMiningIter=\f[R]\f[I]number_of_iterations\f[R] -Controls the number of iterations in the inner strip mined loop. -Strip mining transforms counted loops into two level nested loops. -Safepoints are kept in the outer loop while the inner loop can execute -at full speed. -This option controls the maximum number of iterations in the inner loop. -The default value is 1,000. -.TP -\f[V]-XX:LoopStripMiningIterShortLoop=\f[R]\f[I]number_of_iterations\f[R] -Controls loop strip mining optimization. -Loops with the number of iterations less than specified will not have -safepoints in them. -Default value is 1/10th of \f[V]-XX:LoopStripMiningIter\f[R]. -.TP -\f[V]-XX:+UseFMA\f[R] -Enables hardware-based FMA intrinsics for hardware where FMA -instructions are available (such as, Intel and ARM64). -FMA intrinsics are generated for the -\f[V]java.lang.Math.fma(\f[R]\f[I]a\f[R]\f[V],\f[R] -\f[I]b\f[R]\f[V],\f[R] \f[I]c\f[R]\f[V])\f[R] methods that calculate the -value of \f[V](\f[R] \f[I]a\f[R] \f[V]*\f[R] \f[I]b\f[R] \f[V]+\f[R] -\f[I]c\f[R] \f[V])\f[R] expressions. -.TP -\f[V]-XX:+UseSuperWord\f[R] -Enables the transformation of scalar operations into superword -operations. -Superword is a vectorization optimization. -This option is enabled by default. -To disable the transformation of scalar operations into superword -operations, specify \f[V]-XX:-UseSuperWord\f[R]. -.SH ADVANCED SERVICEABILITY OPTIONS FOR JAVA -.PP -These \f[V]java\f[R] options provide the ability to gather system -information and perform extensive debugging. -.TP -\f[V]-XX:+DisableAttachMechanism\f[R] -Disables the mechanism that lets tools attach to the JVM. -By default, this option is disabled, meaning that the attach mechanism -is enabled and you can use diagnostics and troubleshooting tools such as -\f[V]jcmd\f[R], \f[V]jstack\f[R], \f[V]jmap\f[R], and \f[V]jinfo\f[R]. -.RS -.RS -.PP -\f[B]Note:\f[R] The tools such as \f[B]jcmd\f[R], \f[B]jinfo\f[R], -\f[B]jmap\f[R], and \f[B]jstack\f[R] shipped with the JDK aren\[aq]t -supported when using the tools from one JDK version to troubleshoot a -different JDK version. -.RE -.RE -.TP -\f[V]-XX:+DTraceAllocProbes\f[R] -\f[B]Linux and macOS:\f[R] Enable \f[V]dtrace\f[R] tool probes for -object allocation. -.TP -\f[V]-XX:+DTraceMethodProbes\f[R] -\f[B]Linux and macOS:\f[R] Enable \f[V]dtrace\f[R] tool probes for -method-entry and method-exit. -.TP -\f[V]-XX:+DTraceMonitorProbes\f[R] -\f[B]Linux and macOS:\f[R] Enable \f[V]dtrace\f[R] tool probes for -monitor events. -.TP -\f[V]-XX:+HeapDumpOnOutOfMemoryError\f[R] -Enables the dumping of the Java heap to a file in the current directory -by using the heap profiler (HPROF) when a -\f[V]java.lang.OutOfMemoryError\f[R] exception is thrown. -You can explicitly set the heap dump file path and name using the -\f[V]-XX:HeapDumpPath\f[R] option. -By default, this option is disabled and the heap isn\[aq]t dumped when -an \f[V]OutOfMemoryError\f[R] exception is thrown. -.TP -\f[V]-XX:HeapDumpPath=\f[R]\f[I]path\f[R] -Sets the path and file name for writing the heap dump provided by the -heap profiler (HPROF) when the \f[V]-XX:+HeapDumpOnOutOfMemoryError\f[R] -option is set. -By default, the file is created in the current working directory, and -it\[aq]s named \f[V]java_pid.hprof\f[R] where \f[V]\f[R] is -the identifier of the process that caused the error. -The following example shows how to set the default file explicitly -(\f[V]%p\f[R] represents the current process identifier): -.RS -.RS -.PP -\f[V]-XX:HeapDumpPath=./java_pid%p.hprof\f[R] -.RE -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] The following example shows how to set the heap -dump file to \f[V]/var/log/java/java_heapdump.hprof\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:HeapDumpPath=/var/log/java/java_heapdump.hprof\f[R] -.RE -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] The following example shows how to set the heap dump -file to \f[V]C:/log/java/java_heapdump.log\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:HeapDumpPath=C:/log/java/java_heapdump.log\f[R] -.RE -.RE -.RE -.TP -\f[V]-XX:LogFile=\f[R]\f[I]path\f[R] -Sets the path and file name to where log data is written. -By default, the file is created in the current working directory, and -it\[aq]s named \f[V]hotspot.log\f[R]. -.RS -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] The following example shows how to set the log -file to \f[V]/var/log/java/hotspot.log\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:LogFile=/var/log/java/hotspot.log\f[R] -.RE -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] The following example shows how to set the log file -to \f[V]C:/log/java/hotspot.log\f[R]: -.RS 2 -.RS -.PP -\f[V]-XX:LogFile=C:/log/java/hotspot.log\f[R] -.RE -.RE -.RE -.TP -\f[V]-XX:+PrintClassHistogram\f[R] -Enables printing of a class instance histogram after one of the -following events: -.RS -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] \f[V]Control+\[rs]\f[R] (\f[V]SIGQUIT\f[R]) -.IP \[bu] 2 -\f[B]Windows:\f[R] \f[V]Control+C\f[R] (\f[V]SIGTERM\f[R]) -.PP -By default, this option is disabled. -.PP -Setting this option is equivalent to running the \f[V]jmap -histo\f[R] -command, or the \f[V]jcmd\f[R] \f[I]pid\f[R] -\f[V]GC.class_histogram\f[R] command, where \f[I]pid\f[R] is the current -Java process identifier. -.RE -.TP -\f[V]-XX:+PrintConcurrentLocks\f[R] -Enables printing of \f[V]java.util.concurrent\f[R] locks after one of -the following events: -.RS -.IP \[bu] 2 -\f[B]Non-Windows:\f[R] \f[V]Control+\[rs]\f[R] (\f[V]SIGQUIT\f[R]) -.IP \[bu] 2 -\f[B]Windows:\f[R] \f[V]Control+C\f[R] (\f[V]SIGTERM\f[R]) -.PP -By default, this option is disabled. -.PP -Setting this option is equivalent to running the \f[V]jstack -l\f[R] -command or the \f[V]jcmd\f[R] \f[I]pid\f[R] \f[V]Thread.print -l\f[R] -command, where \f[I]pid\f[R] is the current Java process identifier. -.RE -.TP -\f[V]-XX:+PrintFlagsRanges\f[R] -Prints the range specified and allows automatic testing of the values. -See \f[B]Validate Java Virtual Machine Flag Arguments\f[R]. -.TP -\f[V]-XX:+PerfDataSaveToFile\f[R] -If enabled, saves \f[B]jstat\f[R] binary data when the Java application -exits. -This binary data is saved in a file named -\f[V]hsperfdata_\f[R]\f[I]pid\f[R], where \f[I]pid\f[R] is the process -identifier of the Java application that you ran. -Use the \f[V]jstat\f[R] command to display the performance data -contained in this file as follows: -.RS -.RS -.PP -\f[V]jstat -class file:///\f[R]\f[I]path\f[R]\f[V]/hsperfdata_\f[R]\f[I]pid\f[R] -.RE -.RS -.PP -\f[V]jstat -gc file:///\f[R]\f[I]path\f[R]\f[V]/hsperfdata_\f[R]\f[I]pid\f[R] -.RE -.RE -.TP -\f[V]-XX:+UsePerfData\f[R] -Enables the \f[V]perfdata\f[R] feature. -This option is enabled by default to allow JVM monitoring and -performance testing. -Disabling it suppresses the creation of the \f[V]hsperfdata_userid\f[R] -directories. -To disable the \f[V]perfdata\f[R] feature, specify -\f[V]-XX:-UsePerfData\f[R]. -.SH ADVANCED GARBAGE COLLECTION OPTIONS FOR JAVA -.PP -These \f[V]java\f[R] options control how garbage collection (GC) is -performed by the Java HotSpot VM. -.TP -\f[V]-XX:+AggressiveHeap\f[R] -Enables Java heap optimization. -This sets various parameters to be optimal for long-running jobs with -intensive memory allocation, based on the configuration of the computer -(RAM and CPU). -By default, the option is disabled and the heap sizes are configured -less aggressively. -.TP -\f[V]-XX:+AlwaysPreTouch\f[R] -Requests the VM to touch every page on the Java heap after requesting it -from the operating system and before handing memory out to the -application. -By default, this option is disabled and all pages are committed as the -application uses the heap space. -.TP -\f[V]-XX:ConcGCThreads=\f[R]\f[I]threads\f[R] -Sets the number of threads used for concurrent GC. -Sets \f[I]\f[VI]threads\f[I]\f[R] to approximately 1/4 of the number of -parallel garbage collection threads. -The default value depends on the number of CPUs available to the JVM. -.RS -.PP -For example, to set the number of threads for concurrent GC to 2, -specify the following option: -.RS -.PP -\f[V]-XX:ConcGCThreads=2\f[R] -.RE -.RE -.TP -\f[V]-XX:+DisableExplicitGC\f[R] -Enables the option that disables processing of calls to the -\f[V]System.gc()\f[R] method. -This option is disabled by default, meaning that calls to -\f[V]System.gc()\f[R] are processed. -If processing of calls to \f[V]System.gc()\f[R] is disabled, then the -JVM still performs GC when necessary. -.TP -\f[V]-XX:+ExplicitGCInvokesConcurrent\f[R] -Enables invoking of concurrent GC by using the \f[V]System.gc()\f[R] -request. -This option is disabled by default and can be enabled only with the -\f[V]-XX:+UseG1GC\f[R] option. -.TP -\f[V]-XX:G1AdaptiveIHOPNumInitialSamples=\f[R]\f[I]number\f[R] -When \f[V]-XX:UseAdaptiveIHOP\f[R] is enabled, this option sets the -number of completed marking cycles used to gather samples until G1 -adaptively determines the optimum value of -\f[V]-XX:InitiatingHeapOccupancyPercent\f[R]. -Before, G1 uses the value of -\f[V]-XX:InitiatingHeapOccupancyPercent\f[R] directly for this purpose. -The default value is 3. -.TP -\f[V]-XX:G1HeapRegionSize=\f[R]\f[I]size\f[R] -Sets the size of the regions into which the Java heap is subdivided when -using the garbage-first (G1) collector. -The value is a power of 2 and can range from 1 MB to 32 MB. -The default region size is determined ergonomically based on the heap -size with a goal of approximately 2048 regions. -.RS -.PP -The following example sets the size of the subdivisions to 16 MB: -.RS -.PP -\f[V]-XX:G1HeapRegionSize=16m\f[R] -.RE -.RE -.TP -\f[V]-XX:G1HeapWastePercent=\f[R]\f[I]percent\f[R] -Sets the percentage of heap that you\[aq]re willing to waste. -The Java HotSpot VM doesn\[aq]t initiate the mixed garbage collection -cycle when the reclaimable percentage is less than the heap waste -percentage. -The default is 5 percent. -.TP -\f[V]-XX:G1MaxNewSizePercent=\f[R]\f[I]percent\f[R] -Sets the percentage of the heap size to use as the maximum for the young -generation size. -The default value is 60 percent of your Java heap. -.RS -.PP -This is an experimental flag. -This setting replaces the \f[V]-XX:DefaultMaxNewGenPercent\f[R] setting. -.RE -.TP -\f[V]-XX:G1MixedGCCountTarget=\f[R]\f[I]number\f[R] -Sets the target number of mixed garbage collections after a marking -cycle to collect old regions with at most -\f[V]G1MixedGCLIveThresholdPercent\f[R] live data. -The default is 8 mixed garbage collections. -The goal for mixed collections is to be within this target number. -.TP -\f[V]-XX:G1MixedGCLiveThresholdPercent=\f[R]\f[I]percent\f[R] -Sets the occupancy threshold for an old region to be included in a mixed -garbage collection cycle. -The default occupancy is 85 percent. -.RS -.PP -This is an experimental flag. -This setting replaces the -\f[V]-XX:G1OldCSetRegionLiveThresholdPercent\f[R] setting. -.RE -.TP -\f[V]-XX:G1NewSizePercent=\f[R]\f[I]percent\f[R] -Sets the percentage of the heap to use as the minimum for the young -generation size. -The default value is 5 percent of your Java heap. -.RS -.PP -This is an experimental flag. -This setting replaces the \f[V]-XX:DefaultMinNewGenPercent\f[R] setting. -.RE -.TP -\f[V]-XX:G1OldCSetRegionThresholdPercent=\f[R]\f[I]percent\f[R] -Sets an upper limit on the number of old regions to be collected during -a mixed garbage collection cycle. -The default is 10 percent of the Java heap. -.TP -\f[V]-XX:G1ReservePercent=\f[R]\f[I]percent\f[R] -Sets the percentage of the heap (0 to 50) that\[aq]s reserved as a false -ceiling to reduce the possibility of promotion failure for the G1 -collector. -When you increase or decrease the percentage, ensure that you adjust the -total Java heap by the same amount. -By default, this option is set to 10%. -.RS -.PP -The following example sets the reserved heap to 20%: -.RS -.PP -\f[V]-XX:G1ReservePercent=20\f[R] -.RE -.RE -.TP -\f[V]-XX:+G1UseAdaptiveIHOP\f[R] -Controls adaptive calculation of the old generation occupancy to start -background work preparing for an old generation collection. -If enabled, G1 uses \f[V]-XX:InitiatingHeapOccupancyPercent\f[R] for the -first few times as specified by the value of -\f[V]-XX:G1AdaptiveIHOPNumInitialSamples\f[R], and after that adaptively -calculates a new optimum value for the initiating occupancy -automatically. -Otherwise, the old generation collection process always starts at the -old generation occupancy determined by -\f[V]-XX:InitiatingHeapOccupancyPercent\f[R]. -.RS -.PP -The default is enabled. -.RE -.TP -\f[V]-XX:InitialHeapSize=\f[R]\f[I]size\f[R] -Sets the initial size (in bytes) of the memory allocation pool. -This value must be either 0, or a multiple of 1024 and greater than 1 -MB. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value is selected at run time based on the system -configuration. -.RS -.PP -The following examples show how to set the size of allocated memory to 6 -MB using various units: -.IP -.nf -\f[CB] --XX:InitialHeapSize=6291456 --XX:InitialHeapSize=6144k --XX:InitialHeapSize=6m -\f[R] -.fi -.PP -If you set this option to 0, then the initial size is set as the sum of -the sizes allocated for the old generation and the young generation. -The size of the heap for the young generation can be set using the -\f[V]-XX:NewSize\f[R] option. -Note that the \f[V]-Xms\f[R] option sets both the minimum and the -initial heap size of the heap. -If \f[V]-Xms\f[R] appears after \f[V]-XX:InitialHeapSize\f[R] on the -command line, then the initial heap size gets set to the value specified -with \f[V]-Xms\f[R]. -.RE -.TP -\f[V]-XX:InitialRAMPercentage=\f[R]\f[I]percent\f[R] -Sets the initial amount of memory that the JVM will use for the Java -heap before applying ergonomics heuristics as a percentage of the -maximum amount determined as described in the \f[V]-XX:MaxRAM\f[R] -option. -The default value is 1.5625 percent. -.RS -.PP -The following example shows how to set the percentage of the initial -amount of memory used for the Java heap: -.RS -.PP -\f[V]-XX:InitialRAMPercentage=5\f[R] -.RE -.RE -.TP -\f[V]-XX:InitialSurvivorRatio=\f[R]\f[I]ratio\f[R] -Sets the initial survivor space ratio used by the throughput garbage -collector (which is enabled by the \f[V]-XX:+UseParallelGC\f[R] option). -Adaptive sizing is enabled by default with the throughput garbage -collector by using the \f[V]-XX:+UseParallelGC\f[R] option, and the -survivor space is resized according to the application behavior, -starting with the initial value. -If adaptive sizing is disabled (using the -\f[V]-XX:-UseAdaptiveSizePolicy\f[R] option), then the -\f[V]-XX:SurvivorRatio\f[R] option should be used to set the size of the -survivor space for the entire execution of the application. -.RS -.PP -The following formula can be used to calculate the initial size of -survivor space (S) based on the size of the young generation (Y), and -the initial survivor space ratio (R): -.RS -.PP -\f[V]S=Y/(R+2)\f[R] -.RE -.PP -The 2 in the equation denotes two survivor spaces. -The larger the value specified as the initial survivor space ratio, the -smaller the initial survivor space size. -.PP -By default, the initial survivor space ratio is set to 8. -If the default value for the young generation space size is used (2 MB), -then the initial size of the survivor space is 0.2 MB. -.PP -The following example shows how to set the initial survivor space ratio -to 4: -.RS -.PP -\f[V]-XX:InitialSurvivorRatio=4\f[R] -.RE -.RE -.TP -\f[V]-XX:InitiatingHeapOccupancyPercent=\f[R]\f[I]percent\f[R] -Sets the percentage of the old generation occupancy (0 to 100) at which -to start the first few concurrent marking cycles for the G1 garbage -collector. -.RS -.PP -By default, the initiating value is set to 45%. -A value of 0 implies nonstop concurrent GC cycles from the beginning -until G1 adaptively sets this value. -.PP -See also the \f[V]-XX:G1UseAdaptiveIHOP\f[R] and -\f[V]-XX:G1AdaptiveIHOPNumInitialSamples\f[R] options. -.PP -The following example shows how to set the initiating heap occupancy to -75%: -.RS -.PP -\f[V]-XX:InitiatingHeapOccupancyPercent=75\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxGCPauseMillis=\f[R]\f[I]time\f[R] -Sets a target for the maximum GC pause time (in milliseconds). -This is a soft goal, and the JVM will make its best effort to achieve -it. -The specified value doesn\[aq]t adapt to your heap size. -By default, for G1 the maximum pause time target is 200 milliseconds. -The other generational collectors do not use a pause time goal by -default. -.RS -.PP -The following example shows how to set the maximum target pause time to -500 ms: -.RS -.PP -\f[V]-XX:MaxGCPauseMillis=500\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxHeapSize=\f[R]\f[I]size\f[R] -Sets the maximum size (in byes) of the memory allocation pool. -This value must be a multiple of 1024 and greater than 2 MB. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value is selected at run time based on the system -configuration. -For server deployments, the options \f[V]-XX:InitialHeapSize\f[R] and -\f[V]-XX:MaxHeapSize\f[R] are often set to the same value. -.RS -.PP -The following examples show how to set the maximum allowed size of -allocated memory to 80 MB using various units: -.IP -.nf -\f[CB] --XX:MaxHeapSize=83886080 --XX:MaxHeapSize=81920k --XX:MaxHeapSize=80m -\f[R] -.fi -.PP -The \f[V]-XX:MaxHeapSize\f[R] option is equivalent to \f[V]-Xmx\f[R]. -.RE -.TP -\f[V]-XX:MaxHeapFreeRatio=\f[R]\f[I]percent\f[R] -Sets the maximum allowed percentage of free heap space (0 to 100) after -a GC event. -If free heap space expands above this value, then the heap is shrunk. -By default, this value is set to 70%. -.RS -.PP -Minimize the Java heap size by lowering the values of the parameters -\f[V]MaxHeapFreeRatio\f[R] (default value is 70%) and -\f[V]MinHeapFreeRatio\f[R] (default value is 40%) with the command-line -options \f[V]-XX:MaxHeapFreeRatio\f[R] and -\f[V]-XX:MinHeapFreeRatio\f[R]. -Lowering \f[V]MaxHeapFreeRatio\f[R] to as low as 10% and -\f[V]MinHeapFreeRatio\f[R] to 5% has successfully reduced the heap size -without too much performance regression; however, results may vary -greatly depending on your application. -Try different values for these parameters until they\[aq]re as low as -possible yet still retain acceptable performance. -.RS -.PP -\f[V]-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5\f[R] -.RE -.PP -Customers trying to keep the heap small should also add the option -\f[V]-XX:-ShrinkHeapInSteps\f[R]. -See \f[B]Performance Tuning Examples\f[R] for a description of using -this option to keep the Java heap small by reducing the dynamic -footprint for embedded applications. -.RE -.TP -\f[V]-XX:MaxMetaspaceSize=\f[R]\f[I]size\f[R] -Sets the maximum amount of native memory that can be allocated for class -metadata. -By default, the size isn\[aq]t limited. -The amount of metadata for an application depends on the application -itself, other running applications, and the amount of memory available -on the system. -.RS -.PP -The following example shows how to set the maximum class metadata size -to 256 MB: -.RS -.PP -\f[V]-XX:MaxMetaspaceSize=256m\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxNewSize=\f[R]\f[I]size\f[R] -Sets the maximum size (in bytes) of the heap for the young generation -(nursery). -The default value is set ergonomically. -.TP -\f[V]-XX:MaxRAM=\f[R]\f[I]size\f[R] -Sets the maximum amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics. -The default value is the maximum amount of available memory to the JVM -process or 128 GB, whichever is lower. -.RS -.PP -The maximum amount of available memory to the JVM process is the minimum -of the machine\[aq]s physical memory and any constraints set by the -environment (e.g. -container). -.PP -Specifying this option disables automatic use of compressed oops if the -combined result of this and other options influencing the maximum amount -of memory is larger than the range of memory addressable by compressed -oops. -See \f[V]-XX:UseCompressedOops\f[R] for further information about -compressed oops. -.PP -The following example shows how to set the maximum amount of available -memory for sizing the Java heap to 2 GB: -.RS -.PP -\f[V]-XX:MaxRAM=2G\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxRAMPercentage=\f[R]\f[I]percent\f[R] -Sets the maximum amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics as a percentage of the maximum -amount determined as described in the \f[V]-XX:MaxRAM\f[R] option. -The default value is 25 percent. -.RS -.PP -Specifying this option disables automatic use of compressed oops if the -combined result of this and other options influencing the maximum amount -of memory is larger than the range of memory addressable by compressed -oops. -See \f[V]-XX:UseCompressedOops\f[R] for further information about -compressed oops. -.PP -The following example shows how to set the percentage of the maximum -amount of memory used for the Java heap: -.RS -.PP -\f[V]-XX:MaxRAMPercentage=75\f[R] -.RE -.RE -.TP -\f[V]-XX:MinRAMPercentage=\f[R]\f[I]percent\f[R] -Sets the maximum amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics as a percentage of the maximum -amount determined as described in the \f[V]-XX:MaxRAM\f[R] option for -small heaps. -A small heap is a heap of approximately 125 MB. -The default value is 50 percent. -.RS -.PP -The following example shows how to set the percentage of the maximum -amount of memory used for the Java heap for small heaps: -.RS -.PP -\f[V]-XX:MinRAMPercentage=75\f[R] -.RE -.RE -.TP -\f[V]-XX:MaxTenuringThreshold=\f[R]\f[I]threshold\f[R] -Sets the maximum tenuring threshold for use in adaptive GC sizing. -The largest value is 15. -The default value is 15 for the parallel (throughput) collector. -.RS -.PP -The following example shows how to set the maximum tenuring threshold to -10: -.RS -.PP -\f[V]-XX:MaxTenuringThreshold=10\f[R] -.RE -.RE -.TP -\f[V]-XX:MetaspaceSize=\f[R]\f[I]size\f[R] -Sets the size of the allocated class metadata space that triggers a -garbage collection the first time it\[aq]s exceeded. -This threshold for a garbage collection is increased or decreased -depending on the amount of metadata used. -The default size depends on the platform. -.TP -\f[V]-XX:MinHeapFreeRatio=\f[R]\f[I]percent\f[R] -Sets the minimum allowed percentage of free heap space (0 to 100) after -a GC event. -If free heap space falls below this value, then the heap is expanded. -By default, this value is set to 40%. -.RS -.PP -Minimize Java heap size by lowering the values of the parameters -\f[V]MaxHeapFreeRatio\f[R] (default value is 70%) and -\f[V]MinHeapFreeRatio\f[R] (default value is 40%) with the command-line -options \f[V]-XX:MaxHeapFreeRatio\f[R] and -\f[V]-XX:MinHeapFreeRatio\f[R]. -Lowering \f[V]MaxHeapFreeRatio\f[R] to as low as 10% and -\f[V]MinHeapFreeRatio\f[R] to 5% has successfully reduced the heap size -without too much performance regression; however, results may vary -greatly depending on your application. -Try different values for these parameters until they\[aq]re as low as -possible, yet still retain acceptable performance. -.RS -.PP -\f[V]-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5\f[R] -.RE -.PP -Customers trying to keep the heap small should also add the option -\f[V]-XX:-ShrinkHeapInSteps\f[R]. -See \f[B]Performance Tuning Examples\f[R] for a description of using -this option to keep the Java heap small by reducing the dynamic -footprint for embedded applications. -.RE -.TP -\f[V]-XX:MinHeapSize=\f[R]\f[I]size\f[R] -Sets the minimum size (in bytes) of the memory allocation pool. -This value must be either 0, or a multiple of 1024 and greater than 1 -MB. -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -The default value is selected at run time based on the system -configuration. -.RS -.PP -The following examples show how to set the minimum size of allocated -memory to 6 MB using various units: -.IP -.nf -\f[CB] --XX:MinHeapSize=6291456 --XX:MinHeapSize=6144k --XX:MinHeapSize=6m -\f[R] -.fi -.PP -If you set this option to 0, then the minimum size is set to the same -value as the initial size. -.RE -.TP -\f[V]-XX:NewRatio=\f[R]\f[I]ratio\f[R] -Sets the ratio between young and old generation sizes. -By default, this option is set to 2. -The following example shows how to set the young-to-old ratio to 1: -.RS -.RS -.PP -\f[V]-XX:NewRatio=1\f[R] -.RE -.RE -.TP -\f[V]-XX:NewSize=\f[R]\f[I]size\f[R] -Sets the initial size (in bytes) of the heap for the young generation -(nursery). -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -.RS -.PP -The young generation region of the heap is used for new objects. -GC is performed in this region more often than in other regions. -If the size for the young generation is too low, then a large number of -minor GCs are performed. -If the size is too high, then only full GCs are performed, which can -take a long time to complete. -It is recommended that you keep the size for the young generation -greater than 25% and less than 50% of the overall heap size. -.PP -The following examples show how to set the initial size of the young -generation to 256 MB using various units: -.IP -.nf -\f[CB] --XX:NewSize=256m --XX:NewSize=262144k --XX:NewSize=268435456 -\f[R] -.fi -.PP -The \f[V]-XX:NewSize\f[R] option is equivalent to \f[V]-Xmn\f[R]. -.RE -.TP -\f[V]-XX:ParallelGCThreads=\f[R]\f[I]threads\f[R] -Sets the number of the stop-the-world (STW) worker threads. -The default value depends on the number of CPUs available to the JVM and -the garbage collector selected. -.RS -.PP -For example, to set the number of threads for G1 GC to 2, specify the -following option: -.RS -.PP -\f[V]-XX:ParallelGCThreads=2\f[R] -.RE -.RE -.TP -\f[V]-XX:+ParallelRefProcEnabled\f[R] -Enables parallel reference processing. -By default, this option is disabled. -.TP -\f[V]-XX:+PrintAdaptiveSizePolicy\f[R] -Enables printing of information about adaptive-generation sizing. -By default, this option is disabled. -.TP -\f[V]-XX:SoftRefLRUPolicyMSPerMB=\f[R]\f[I]time\f[R] -Sets the amount of time (in milliseconds) a softly reachable object is -kept active on the heap after the last time it was referenced. -The default value is one second of lifetime per free megabyte in the -heap. -The \f[V]-XX:SoftRefLRUPolicyMSPerMB\f[R] option accepts integer values -representing milliseconds per one megabyte of the current heap size (for -Java HotSpot Client VM) or the maximum possible heap size (for Java -HotSpot Server VM). -This difference means that the Client VM tends to flush soft references -rather than grow the heap, whereas the Server VM tends to grow the heap -rather than flush soft references. -In the latter case, the value of the \f[V]-Xmx\f[R] option has a -significant effect on how quickly soft references are garbage collected. -.RS -.PP -The following example shows how to set the value to 2.5 seconds: -.PP -\f[V]-XX:SoftRefLRUPolicyMSPerMB=2500\f[R] -.RE -.TP -\f[V]-XX:-ShrinkHeapInSteps\f[R] -Incrementally reduces the Java heap to the target size, specified by the -option \f[V]-XX:MaxHeapFreeRatio\f[R]. -This option is enabled by default. -If disabled, then it immediately reduces the Java heap to the target -size instead of requiring multiple garbage collection cycles. -Disable this option if you want to minimize the Java heap size. -You will likely encounter performance degradation when this option is -disabled. -.RS -.PP -See \f[B]Performance Tuning Examples\f[R] for a description of using the -\f[V]MaxHeapFreeRatio\f[R] option to keep the Java heap small by -reducing the dynamic footprint for embedded applications. -.RE -.TP -\f[V]-XX:StringDeduplicationAgeThreshold=\f[R]\f[I]threshold\f[R] -Identifies \f[V]String\f[R] objects reaching the specified age that are -considered candidates for deduplication. -An object\[aq]s age is a measure of how many times it has survived -garbage collection. -This is sometimes referred to as tenuring. -.RS -.RS -.PP -\f[B]Note:\f[R] \f[V]String\f[R] objects that are promoted to an old -heap region before this age has been reached are always considered -candidates for deduplication. -The default value for this option is \f[V]3\f[R]. -See the \f[V]-XX:+UseStringDeduplication\f[R] option. -.RE -.RE -.TP -\f[V]-XX:SurvivorRatio=\f[R]\f[I]ratio\f[R] -Sets the ratio between eden space size and survivor space size. -By default, this option is set to 8. -The following example shows how to set the eden/survivor space ratio to -4: -.RS -.RS -.PP -\f[V]-XX:SurvivorRatio=4\f[R] -.RE -.RE -.TP -\f[V]-XX:TargetSurvivorRatio=\f[R]\f[I]percent\f[R] -Sets the desired percentage of survivor space (0 to 100) used after -young garbage collection. -By default, this option is set to 50%. -.RS -.PP -The following example shows how to set the target survivor space ratio -to 30%: -.RS -.PP -\f[V]-XX:TargetSurvivorRatio=30\f[R] -.RE -.RE -.TP -\f[V]-XX:TLABSize=\f[R]\f[I]size\f[R] -Sets the initial size (in bytes) of a thread-local allocation buffer -(TLAB). -Append the letter \f[V]k\f[R] or \f[V]K\f[R] to indicate kilobytes, -\f[V]m\f[R] or \f[V]M\f[R] to indicate megabytes, or \f[V]g\f[R] or -\f[V]G\f[R] to indicate gigabytes. -If this option is set to 0, then the JVM selects the initial size -automatically. -.RS -.PP -The following example shows how to set the initial TLAB size to 512 KB: -.RS -.PP -\f[V]-XX:TLABSize=512k\f[R] -.RE -.RE -.TP -\f[V]-XX:+UseAdaptiveSizePolicy\f[R] -Enables the use of adaptive generation sizing. -This option is enabled by default. -To disable adaptive generation sizing, specify -\f[V]-XX:-UseAdaptiveSizePolicy\f[R] and set the size of the memory -allocation pool explicitly. -See the \f[V]-XX:SurvivorRatio\f[R] option. -.TP -\f[V]-XX:+UseG1GC\f[R] -Enables the use of the garbage-first (G1) garbage collector. -It\[aq]s a server-style garbage collector, targeted for multiprocessor -machines with a large amount of RAM. -This option meets GC pause time goals with high probability, while -maintaining good throughput. -The G1 collector is recommended for applications requiring large heaps -(sizes of around 6 GB or larger) with limited GC latency requirements (a -stable and predictable pause time below 0.5 seconds). -By default, this option is enabled and G1 is used as the default garbage -collector. -.TP -\f[V]-XX:+UseGCOverheadLimit\f[R] -Enables the use of a policy that limits the proportion of time spent by -the JVM on GC before an \f[V]OutOfMemoryError\f[R] exception is thrown. -This option is enabled, by default, and the parallel GC will throw an -\f[V]OutOfMemoryError\f[R] if more than 98% of the total time is spent -on garbage collection and less than 2% of the heap is recovered. -When the heap is small, this feature can be used to prevent applications -from running for long periods of time with little or no progress. -To disable this option, specify the option -\f[V]-XX:-UseGCOverheadLimit\f[R]. -.TP -\f[V]-XX:+UseNUMA\f[R] -Enables performance optimization of an application on a machine with -nonuniform memory architecture (NUMA) by increasing the -application\[aq]s use of lower latency memory. -By default, this option is disabled and no optimization for NUMA is -made. -The option is available only when the parallel garbage collector is used -(\f[V]-XX:+UseParallelGC\f[R]). -.TP -\f[V]-XX:+UseParallelGC\f[R] -Enables the use of the parallel scavenge garbage collector (also known -as the throughput collector) to improve the performance of your -application by leveraging multiple processors. -.RS -.PP -By default, this option is disabled and the default collector is used. -.RE -.TP -\f[V]-XX:+UseSerialGC\f[R] -Enables the use of the serial garbage collector. -This is generally the best choice for small and simple applications that -don\[aq]t require any special functionality from garbage collection. -By default, this option is disabled and the default collector is used. -.TP -\f[V]-XX:+UseStringDeduplication\f[R] -Enables string deduplication. -By default, this option is disabled. -To use this option, you must enable the garbage-first (G1) garbage -collector. -.RS -.PP -String deduplication reduces the memory footprint of \f[V]String\f[R] -objects on the Java heap by taking advantage of the fact that many -\f[V]String\f[R] objects are identical. -Instead of each \f[V]String\f[R] object pointing to its own character -array, identical \f[V]String\f[R] objects can point to and share the -same character array. -.RE -.TP -\f[V]-XX:+UseTLAB\f[R] -Enables the use of thread-local allocation blocks (TLABs) in the young -generation space. -This option is enabled by default. -To disable the use of TLABs, specify the option \f[V]-XX:-UseTLAB\f[R]. -.TP -\f[V]-XX:+UseZGC\f[R] -Enables the use of the Z garbage collector (ZGC). -This is a low latency garbage collector, providing max pause times of a -few milliseconds, at some throughput cost. -Pause times are independent of what heap size is used. -Supports heap sizes from 8MB to 16TB. -.TP -\f[V]-XX:ZAllocationSpikeTolerance=\f[R]\f[I]factor\f[R] -Sets the allocation spike tolerance for ZGC. -By default, this option is set to 2.0. -This factor describes the level of allocation spikes to expect. -For example, using a factor of 3.0 means the current allocation rate can -be expected to triple at any time. -.TP -\f[V]-XX:ZCollectionInterval=\f[R]\f[I]seconds\f[R] -Sets the maximum interval (in seconds) between two GC cycles when using -ZGC. -By default, this option is set to 0 (disabled). -.TP -\f[V]-XX:ZFragmentationLimit=\f[R]\f[I]percent\f[R] -Sets the maximum acceptable heap fragmentation (in percent) for ZGC. -By default, this option is set to 25. -Using a lower value will cause the heap to be compacted more -aggressively, to reclaim more memory at the cost of using more CPU time. -.TP -\f[V]-XX:+ZProactive\f[R] -Enables proactive GC cycles when using ZGC. -By default, this option is enabled. -ZGC will start a proactive GC cycle if doing so is expected to have -minimal impact on the running application. -This is useful if the application is mostly idle or allocates very few -objects, but you still want to keep the heap size down and allow -reference processing to happen even when there are a lot of free space -on the heap. -.TP -\f[V]-XX:+ZUncommit\f[R] -Enables uncommitting of unused heap memory when using ZGC. -By default, this option is enabled. -Uncommitting unused heap memory will lower the memory footprint of the -JVM, and make that memory available for other processes to use. -.TP -\f[V]-XX:ZUncommitDelay=\f[R]\f[I]seconds\f[R] -Sets the amount of time (in seconds) that heap memory must have been -unused before being uncommitted. -By default, this option is set to 300 (5 minutes). -Committing and uncommitting memory are relatively expensive operations. -Using a lower value will cause heap memory to be uncommitted earlier, at -the risk of soon having to commit it again. -.SH DEPRECATED JAVA OPTIONS -.PP -These \f[V]java\f[R] options are deprecated and might be removed in a -future JDK release. -They\[aq]re still accepted and acted upon, but a warning is issued when -they\[aq]re used. -.TP -\f[V]-Xloggc:\f[R]\f[I]filename\f[R] -Sets the file to which verbose GC events information should be -redirected for logging. -The \f[V]-Xloggc\f[R] option overrides \f[V]-verbose:gc\f[R] if both are -given with the same java command. -\f[V]-Xloggc:\f[R]\f[I]filename\f[R] is replaced by -\f[V]-Xlog:gc:\f[R]\f[I]filename\f[R]. -See Enable Logging with the JVM Unified Logging Framework. -.RS -.PP -Example: -.PP -\f[V]-Xlog:gc:garbage-collection.log\f[R] -.RE -.TP -\f[V]-XX:+FlightRecorder\f[R] -Enables the use of Java Flight Recorder (JFR) during the runtime of the -application. -Since JDK 8u40 this option has not been required to use JFR. -.SH OBSOLETE JAVA OPTIONS -.PP -These \f[V]java\f[R] options are still accepted but ignored, and a -warning is issued when they\[aq]re used. -.TP -\f[V]--illegal-access=\f[R]\f[I]parameter\f[R] -Controlled \f[I]relaxed strong encapsulation\f[R], as defined in -\f[B]JEP 261\f[R] -[https://openjdk.org/jeps/261#Relaxed-strong-encapsulation]. -This option was deprecated in JDK 16 by \f[B]JEP 396\f[R] -[https://openjdk.org/jeps/396] and made obsolete in JDK 17 by \f[B]JEP -403\f[R] [https://openjdk.org/jeps/403]. -.TP -\f[V]-XX:RTMAbortRatio=\f[R]\f[I]abort_ratio\f[R] -Specifies the RTM abort ratio is specified as a percentage (%) of all -executed RTM transactions. -If a number of aborted transactions becomes greater than this ratio, -then the compiled code is deoptimized. -This ratio is used when the \f[V]-XX:+UseRTMDeopt\f[R] option is -enabled. -The default value of this option is 50. -This means that the compiled code is deoptimized if 50% of all -transactions are aborted. -.TP -\f[V]-XX:RTMRetryCount=\f[R]\f[I]number_of_retries\f[R] -Specifies the number of times that the RTM locking code is retried, when -it is aborted or busy, before falling back to the normal locking -mechanism. -The default value for this option is 5. -The \f[V]-XX:UseRTMLocking\f[R] option must be enabled. -.TP -\f[V]-XX:+UseRTMDeopt\f[R] -Autotunes RTM locking depending on the abort ratio. -This ratio is specified by the \f[V]-XX:RTMAbortRatio\f[R] option. -If the number of aborted transactions exceeds the abort ratio, then the -method containing the lock is deoptimized and recompiled with all locks -as normal locks. -This option is disabled by default. -The \f[V]-XX:+UseRTMLocking\f[R] option must be enabled. -.TP -\f[V]-XX:+UseRTMLocking\f[R] -Generates Restricted Transactional Memory (RTM) locking code for all -inflated locks, with the normal locking mechanism as the fallback -handler. -This option is disabled by default. -Options related to RTM are available only on x86 CPUs that support -Transactional Synchronization Extensions (TSX). -.RS -.PP -RTM is part of Intel\[aq]s TSX, which is an x86 instruction set -extension and facilitates the creation of multithreaded applications. -RTM introduces the new instructions \f[V]XBEGIN\f[R], \f[V]XABORT\f[R], -\f[V]XEND\f[R], and \f[V]XTEST\f[R]. -The \f[V]XBEGIN\f[R] and \f[V]XEND\f[R] instructions enclose a set of -instructions to run as a transaction. -If no conflict is found when running the transaction, then the memory -and register modifications are committed together at the \f[V]XEND\f[R] -instruction. -The \f[V]XABORT\f[R] instruction can be used to explicitly abort a -transaction and the \f[V]XTEST\f[R] instruction checks if a set of -instructions is being run in a transaction. -.PP -A lock on a transaction is inflated when another thread tries to access -the same transaction, thereby blocking the thread that didn\[aq]t -originally request access to the transaction. -RTM requires that a fallback set of operations be specified in case a -transaction aborts or fails. -An RTM lock is a lock that has been delegated to the TSX\[aq]s system. -.PP -RTM improves performance for highly contended locks with low conflict in -a critical region (which is code that must not be accessed by more than -one thread concurrently). -RTM also improves the performance of coarse-grain locking, which -typically doesn\[aq]t perform well in multithreaded applications. -(Coarse-grain locking is the strategy of holding locks for long periods -to minimize the overhead of taking and releasing locks, while -fine-grained locking is the strategy of trying to achieve maximum -parallelism by locking only when necessary and unlocking as soon as -possible.) -Also, for lightly contended locks that are used by different threads, -RTM can reduce false cache line sharing, also known as cache line -ping-pong. -This occurs when multiple threads from different processors are -accessing different resources, but the resources share the same cache -line. -As a result, the processors repeatedly invalidate the cache lines of -other processors, which forces them to read from main memory instead of -their cache. -.RE -.SH REMOVED JAVA OPTIONS -.PP -These \f[V]java\f[R] options have been removed in JDK 24 and using them -results in an error of: -.RS -.PP -\f[V]Unrecognized VM option\f[R] \f[I]option-name\f[R] -.RE -.TP -\f[V]-XX:InitialRAMFraction=\f[R]\f[I]ratio\f[R] -Sets the initial amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics as a ratio of the maximum amount -determined as described in the \f[V]-XX:MaxRAM\f[R] option. -The default value is 64. -.RS -.PP -Use the option \f[V]-XX:InitialRAMPercentage\f[R] instead. -.RE -.TP -\f[V]-XX:MaxRAMFraction=\f[R]\f[I]ratio\f[R] -Sets the maximum amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics as a fraction of the maximum -amount determined as described in the \f[V]-XX:MaxRAM\f[R] option. -The default value is 4. -.RS -.PP -Specifying this option disables automatic use of compressed oops if the -combined result of this and other options influencing the maximum amount -of memory is larger than the range of memory addressable by compressed -oops. -See \f[V]-XX:UseCompressedOops\f[R] for further information about -compressed oops. -.PP -Use the option \f[V]-XX:MaxRAMPercentage\f[R] instead. -.RE -.TP -\f[V]-XX:MinRAMFraction=\f[R]\f[I]ratio\f[R] -Sets the maximum amount of memory that the JVM may use for the Java heap -before applying ergonomics heuristics as a fraction of the maximum -amount determined as described in the \f[V]-XX:MaxRAM\f[R] option for -small heaps. -A small heap is a heap of approximately 125 MB. -The default value is 2. -.RS -.PP -Use the option \f[V]-XX:MinRAMPercentage\f[R] instead. -.RE -.TP -\f[V]-XX:+ScavengeBeforeFullGC\f[R] -Enables GC of the young generation before each full GC. -This option is enabled by default. -It is recommended that you \f[I]don\[aq]t\f[R] disable it, because -scavenging the young generation before a full GC can reduce the number -of objects reachable from the old generation space into the young -generation space. -To disable GC of the young generation before each full GC, specify the -option \f[V]-XX:-ScavengeBeforeFullGC\f[R]. -.TP -\f[V]-Xfuture\f[R] -Enables strict class-file format checks that enforce close conformance -to the class-file format specification. -Developers should use this flag when developing new code. -Stricter checks may become the default in future releases. -.RS -.PP -Use the option \f[V]-Xverify:all\f[R] instead. -.RE -.PP -For the lists and descriptions of options removed in previous releases -see the \f[I]Removed Java Options\f[R] section in: -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 23\f[R] -[https://docs.oracle.com/en/java/javase/23/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 22\f[R] -[https://docs.oracle.com/en/java/javase/22/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 21\f[R] -[https://docs.oracle.com/en/java/javase/21/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 20\f[R] -[https://docs.oracle.com/en/java/javase/20/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 19\f[R] -[https://docs.oracle.com/en/java/javase/19/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 18\f[R] -[https://docs.oracle.com/en/java/javase/18/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 17\f[R] -[https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 16\f[R] -[https://docs.oracle.com/en/java/javase/16/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 15\f[R] -[https://docs.oracle.com/en/java/javase/15/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 14\f[R] -[https://docs.oracle.com/en/java/javase/14/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]The \f[VB]java\f[B] Command, Release 13\f[R] -[https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 12\f[R] -[https://docs.oracle.com/en/java/javase/12/tools/java.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 11\f[R] -[https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 10\f[R] -[https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 9\f[R] -[https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 8 for -Oracle JDK on Windows\f[R] -[https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html#BGBCIEFC] -.IP \[bu] 2 -\f[B]Java Platform, Standard Edition Tools Reference, Release 8 for -Oracle JDK on Solaris, Linux, and macOS\f[R] -[https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC] -.SH JAVA COMMAND-LINE ARGUMENT FILES -.PP -You can shorten or simplify the \f[V]java\f[R] command by using -\f[V]\[at]\f[R] argument files to specify one or more text files that -contain arguments, such as options and class names, which are passed to -the \f[V]java\f[R] command. -This let\[aq]s you to create \f[V]java\f[R] commands of any length on -any operating system. -.PP -In the command line, use the at sign (\f[V]\[at]\f[R]) prefix to -identify an argument file that contains \f[V]java\f[R] options and class -names. -When the \f[V]java\f[R] command encounters a file beginning with the at -sign (\f[V]\[at]\f[R]), it expands the contents of that file into an -argument list just as they would be specified on the command line. -.PP -The \f[V]java\f[R] launcher expands the argument file contents until it -encounters the \f[V]--disable-\[at]files\f[R] option. -You can use the \f[V]--disable-\[at]files\f[R] option anywhere on the -command line, including in an argument file, to stop \f[V]\[at]\f[R] -argument files expansion. -.PP -The following items describe the syntax of \f[V]java\f[R] argument -files: -.IP \[bu] 2 -The argument file must contain only ASCII characters or characters in -system default encoding that\[aq]s ASCII friendly, such as UTF-8. -.IP \[bu] 2 -The argument file size must not exceed MAXINT (2,147,483,647) bytes. -.IP \[bu] 2 -The launcher doesn\[aq]t expand wildcards that are present within an -argument file. -.IP \[bu] 2 -Use white space or new line characters to separate arguments included in -the file. -.IP \[bu] 2 -White space includes a white space character, \f[V]\[rs]t\f[R], -\f[V]\[rs]n\f[R], \f[V]\[rs]r\f[R], and \f[V]\[rs]f\f[R]. -.RS 2 -.PP -For example, it is possible to have a path with a space, such as -\f[V]c:\[rs]Program Files\f[R] that can be specified as either -\f[V]\[dq]c:\[rs]\[rs]Program Files\[dq]\f[R] or, to avoid an escape, -\f[V]c:\[rs]Program\[dq] \[dq]Files\f[R]. -.RE -.IP \[bu] 2 -Any option that contains spaces, such as a path component, must be -within quotation marks using quotation (\[aq]\[dq]\[aq]) characters in -its entirety. -.IP \[bu] 2 -A string within quotation marks may contain the characters -\f[V]\[rs]n\f[R], \f[V]\[rs]r\f[R], \f[V]\[rs]t\f[R], and -\f[V]\[rs]f\f[R]. -They are converted to their respective ASCII codes. -.IP \[bu] 2 -If a file name contains embedded spaces, then put the whole file name in -double quotation marks. -.IP \[bu] 2 -File names in an argument file are relative to the current directory, -not to the location of the argument file. -.IP \[bu] 2 -Use the number sign \f[V]#\f[R] in the argument file to identify -comments. -All characters following the \f[V]#\f[R] are ignored until the end of -line. -.IP \[bu] 2 -Additional at sign \f[V]\[at]\f[R] prefixes to \f[V]\[at]\f[R] prefixed -options act as an escape, (the first \f[V]\[at]\f[R] is removed and the -rest of the arguments are presented to the launcher literally). -.IP \[bu] 2 -Lines may be continued using the continuation character -(\f[V]\[rs]\f[R]) at the end-of-line. -The two lines are concatenated with the leading white spaces trimmed. -To prevent trimming the leading white spaces, a continuation character -(\f[V]\[rs]\f[R]) may be placed at the first column. -.IP \[bu] 2 -Because backslash (\[rs]) is an escape character, a backslash character -must be escaped with another backslash character. -.IP \[bu] 2 -Partial quote is allowed and is closed by an end-of-file. -.IP \[bu] 2 -An open quote stops at end-of-line unless \f[V]\[rs]\f[R] is the last -character, which then joins the next line by removing all leading white -space characters. -.IP \[bu] 2 -Wildcards (*) aren\[aq]t allowed in these lists (such as specifying -\f[V]*.java\f[R]). -.IP \[bu] 2 -Use of the at sign (\f[V]\[at]\f[R]) to recursively interpret files -isn\[aq]t supported. -.SS Example of Open or Partial Quotes in an Argument File -.PP -In the argument file, -.IP -.nf -\f[CB] --cp \[dq]lib/ -cool/ -app/ -jars -\f[R] -.fi -.PP -this is interpreted as: -.RS -.PP -\f[V]-cp lib/cool/app/jars\f[R] -.RE -.SS Example of a Backslash Character Escaped with Another Backslash Character in an Argument File -.PP -To output the following: -.RS -.PP -\f[V]-cp c:\[rs]Program Files (x86)\[rs]Java\[rs]jre\[rs]lib\[rs]ext;c:\[rs]Program Files\[rs]Java\[rs]jre9\[rs]lib\[rs]ext\f[R] -.RE -.PP -The backslash character must be specified in the argument file as: -.RS -.PP -\f[V]-cp \[dq]c:\[rs]\[rs]Program Files (x86)\[rs]\[rs]Java\[rs]\[rs]jre\[rs]\[rs]lib\[rs]\[rs]ext;c:\[rs]\[rs]Program Files\[rs]\[rs]Java\[rs]\[rs]jre9\[rs]\[rs]lib\[rs]\[rs]ext\[dq]\f[R] -.RE -.SS Example of an EOL Escape Used to Force Concatenation of Lines in an Argument File -.PP -In the argument file, -.IP -.nf -\f[CB] --cp \[dq]/lib/cool app/jars:\[rs] - /lib/another app/jars\[dq] -\f[R] -.fi -.PP -This is interpreted as: -.RS -.PP -\f[V]-cp /lib/cool app/jars:/lib/another app/jars\f[R] -.RE -.SS Example of Line Continuation with Leading Spaces in an Argument File -.PP -In the argument file, -.IP -.nf -\f[CB] --cp \[dq]/lib/cool\[rs] -\[rs]app/jars\[dq] -\f[R] -.fi -.PP -This is interpreted as: -.PP -\f[V]-cp /lib/cool app/jars\f[R] -.SS Examples of Using Single Argument File -.PP -You can use a single argument file, such as \f[V]myargumentfile\f[R] in -the following example, to hold all required \f[V]java\f[R] arguments: -.RS -.PP -\f[V]java \[at]myargumentfile\f[R] -.RE -.SS Examples of Using Argument Files with Paths -.PP -You can include relative paths in argument files; however, they\[aq]re -relative to the current working directory and not to the paths of the -argument files themselves. -In the following example, \f[V]path1/options\f[R] and -\f[V]path2/options\f[R] represent argument files with different paths. -Any relative paths that they contain are relative to the current working -directory and not to the argument files: -.RS -.PP -\f[V]java \[at]path1/options \[at]path2/classes\f[R] -.RE -.SH CODE HEAP STATE ANALYTICS -.SS Overview -.PP -There are occasions when having insight into the current state of the -JVM code heap would be helpful to answer questions such as: -.IP \[bu] 2 -Why was the JIT turned off and then on again and again? -.IP \[bu] 2 -Where has all the code heap space gone? -.IP \[bu] 2 -Why is the method sweeper not working effectively? -.PP -To provide this insight, a code heap state analytics feature has been -implemented that enables on-the-fly analysis of the code heap. -The analytics process is divided into two parts. -The first part examines the entire code heap and aggregates all -information that is believed to be useful or important. -The second part consists of several independent steps that print the -collected information with an emphasis on different aspects of the data. -Data collection and printing are done on an \[dq]on request\[dq] basis. -.SS Syntax -.PP -Requests for real-time, on-the-fly analysis can be issued with the -following command: -.RS -.PP -\f[V]jcmd\f[R] \f[I]pid\f[R] \f[V]Compiler.CodeHeap_Analytics\f[R] -[\f[I]function\f[R]] [\f[I]granularity\f[R]] -.RE -.PP -If you are only interested in how the code heap looks like after running -a sample workload, you can use the command line option: -.RS -.PP -\f[V]-Xlog:codecache=Trace\f[R] -.RE -.PP -To see the code heap state when a \[dq]CodeCache full\[dq] condition -exists, start the VM with the command line option: -.RS -.PP -\f[V]-Xlog:codecache=Debug\f[R] -.RE -.PP -See \f[B]CodeHeap State Analytics (OpenJDK)\f[R] -[https://bugs.openjdk.org/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] -for a detailed description of the code heap state analytics feature, the -supported functions, and the granularity options. -.SH ENABLE LOGGING WITH THE JVM UNIFIED LOGGING FRAMEWORK -.PP -You use the \f[V]-Xlog\f[R] option to configure or enable logging with -the Java Virtual Machine (JVM) unified logging framework. -.SS Synopsis -.RS -.PP -\f[V]-Xlog\f[R][\f[V]:\f[R][\f[I]what\f[R]][\f[V]:\f[R][\f[I]output\f[R]][\f[V]:\f[R][\f[I]decorators\f[R]][\f[V]:\f[R]\f[I]output-options\f[R][\f[V],\f[R]...]]]]] -.PP -\f[V]-Xlog:\f[R]\f[I]directive\f[R] -.RE -.TP -\f[I]what\f[R] -Specifies a combination of tags and levels of the form -\f[I]tag1\f[R][\f[V]+\f[R]\f[I]tag2\f[R]...][\f[V]*\f[R]][\f[V]=\f[R]\f[I]level\f[R]][\f[V],\f[R]...]. -Unless the wildcard (\f[V]*\f[R]) is specified, only log messages tagged -with exactly the tags specified are matched. -See \f[B]-Xlog Tags and Levels\f[R]. -.TP -\f[I]output\f[R] -Sets the type of output. -Omitting the \f[I]output\f[R] type defaults to \f[V]stdout\f[R]. -See \f[B]-Xlog Output\f[R]. -.TP -\f[I]decorators\f[R] -Configures the output to use a custom set of decorators. -Omitting \f[I]decorators\f[R] defaults to \f[V]uptime\f[R], -\f[V]level\f[R], and \f[V]tags\f[R]. -See \f[B]Decorations\f[R]. -.TP -\f[I]output-options\f[R] -Sets the \f[V]-Xlog\f[R] logging output options. -.TP -\f[I]directive\f[R] -A global option or subcommand: help, disable, async -.SS Description -.PP -The Java Virtual Machine (JVM) unified logging framework provides a -common logging system for all components of the JVM. -GC logging for the JVM has been changed to use the new logging -framework. -The mapping of old GC flags to the corresponding new Xlog configuration -is described in \f[B]Convert GC Logging Flags to Xlog\f[R]. -In addition, runtime logging has also been changed to use the JVM -unified logging framework. -The mapping of legacy runtime logging flags to the corresponding new -Xlog configuration is described in \f[B]Convert Runtime Logging Flags to -Xlog\f[R]. -.PP -The following provides quick reference to the \f[V]-Xlog\f[R] command -and syntax for options: -.TP -\f[V]-Xlog\f[R] -Enables JVM logging on an \f[V]info\f[R] level. -.TP -\f[V]-Xlog:help\f[R] -Prints \f[V]-Xlog\f[R] usage syntax and available tags, levels, and -decorators along with example command lines with explanations. -.TP -\f[V]-Xlog:disable\f[R] -Turns off all logging and clears all configuration of the logging -framework including the default configuration for warnings and errors. -.TP -\f[V]-Xlog\f[R][\f[V]:\f[R]\f[I]option\f[R]] -Applies multiple arguments in the order that they appear on the command -line. -Multiple \f[V]-Xlog\f[R] arguments for the same output override each -other in their given order. -.RS -.PP -The \f[I]option\f[R] is set as: -.RS -.PP -[\f[I]tag-selection\f[R]][\f[V]:\f[R][\f[I]output\f[R]][\f[V]:\f[R][\f[I]decorators\f[R]][\f[V]:\f[R]\f[I]output-options\f[R]]]] -.RE -.PP -Omitting the \f[I]tag-selection\f[R] defaults to a tag-set of -\f[V]all\f[R] and a level of \f[V]info\f[R]. -.RS -.PP -\f[I]tag\f[R][\f[V]+\f[R]...] -\f[V]all\f[R] -.RE -.PP -The \f[V]all\f[R] tag is a meta tag consisting of all tag-sets -available. -The asterisk \f[V]*\f[R] in a tag set definition denotes a wildcard tag -match. -Matching with a wildcard selects all tag sets that contain \f[I]at -least\f[R] the specified tags. -Without the wildcard, only exact matches of the specified tag sets are -selected. -.PP -\f[I]output-options\f[R] is -.RS -.PP -\f[V]filecount=\f[R]\f[I]file-count\f[R] \f[V]filesize=\f[R]\f[I]file -size with optional K, M or G suffix\f[R] -\f[V]foldmultilines=\f[R]\f[I]\f[R] -.RE -.PP -When \f[V]foldmultilines\f[R] is true, a log event that consists of -multiple lines will be folded into a single line by replacing newline -characters with the sequence \f[V]\[aq]\[rs]\[aq]\f[R] and -\f[V]\[aq]n\[aq]\f[R] in the output. -Existing single backslash characters will also be replaced with a -sequence of two backslashes so that the conversion can be reversed. -This option is safe to use with UTF-8 character encodings, but other -encodings may not work. -For example, it may incorrectly convert multi-byte sequences in Shift -JIS and BIG5. -.RE -.SS Default Configuration -.PP -When the \f[V]-Xlog\f[R] option and nothing else is specified on the -command line, the default configuration is used. -The default configuration logs all messages with a level that matches -either warning or error regardless of what tags the message is -associated with. -The default configuration is equivalent to entering the following on the -command line: -.RS -.PP -\f[V]-Xlog:all=warning:stdout:uptime,level,tags\f[R] -.RE -.SS Controlling Logging at Runtime -.PP -Logging can also be controlled at run time through Diagnostic Commands -(with the \f[B]jcmd\f[R] utility). -Everything that can be specified on the command line can also be -specified dynamically with the \f[V]VM.log\f[R] command. -As the diagnostic commands are automatically exposed as MBeans, you can -use JMX to change logging configuration at run time. -.SS -Xlog Tags and Levels -.PP -Each log message has a level and a tag set associated with it. -The level of the message corresponds to its details, and the tag set -corresponds to what the message contains or which JVM component it -involves (such as, \f[V]gc\f[R], \f[V]jit\f[R], or \f[V]os\f[R]). -Mapping GC flags to the Xlog configuration is described in \f[B]Convert -GC Logging Flags to Xlog\f[R]. -Mapping legacy runtime logging flags to the corresponding Xlog -configuration is described in \f[B]Convert Runtime Logging Flags to -Xlog\f[R]. -.PP -\f[B]Available log levels:\f[R] -.IP \[bu] 2 -\f[V]off\f[R] -.IP \[bu] 2 -\f[V]trace\f[R] -.IP \[bu] 2 -\f[V]debug\f[R] -.IP \[bu] 2 -\f[V]info\f[R] -.IP \[bu] 2 -\f[V]warning\f[R] -.IP \[bu] 2 -\f[V]error\f[R] -.PP -\f[B]Available log tags:\f[R] -.PP -There are literally dozens of log tags, which in the right combinations, -will enable a range of logging output. -The full set of available log tags can be seen using -\f[V]-Xlog:help\f[R]. -Specifying \f[V]all\f[R] instead of a tag combination matches all tag -combinations. -.SS -Xlog Output -.PP -The \f[V]-Xlog\f[R] option supports the following types of outputs: -.IP \[bu] 2 -\f[V]stdout\f[R] --- Sends output to stdout -.IP \[bu] 2 -\f[V]stderr\f[R] --- Sends output to stderr -.IP \[bu] 2 -\f[V]file=\f[R]\f[I]filename\f[R] --- Sends output to text file(s). -.PP -When using \f[V]file=\f[R]\f[I]filename\f[R], specifying \f[V]%p\f[R], -\f[V]%t\f[R] and/or \f[V]%hn\f[R] in the file name expands to the -JVM\[aq]s PID, startup timestamp and host name, respectively. -You can also configure text files to handle file rotation based on file -size and a number of files to rotate. -For example, to rotate the log file every 10 MB and keep 5 files in -rotation, specify the options \f[V]filesize=10M, filecount=5\f[R]. -The target size of the files isn\[aq]t guaranteed to be exact, it\[aq]s -just an approximate value. -Files are rotated by default with up to 5 rotated files of target size -20 MB, unless configured otherwise. -Specifying \f[V]filecount=0\f[R] means that the log file shouldn\[aq]t -be rotated. -There\[aq]s a possibility of the pre-existing log file getting -overwritten. -.SS -Xlog Output Mode -.PP -By default logging messages are output synchronously - each log message -is written to the designated output when the logging call is made. -But you can instead use asynchronous logging mode by specifying: -.TP -\f[V]-Xlog:async\f[R] -Write all logging asynchronously. -.PP -In asynchronous logging mode, log sites enqueue all logging messages to -an intermediate buffer and a standalone thread is responsible for -flushing them to the corresponding outputs. -The intermediate buffer is bounded and on buffer exhaustion the -enqueuing message is discarded. -Log entry write operations are guaranteed non-blocking. -.PP -The option \f[V]-XX:AsyncLogBufferSize=N\f[R] specifies the memory -budget in bytes for the intermediate buffer. -The default value should be big enough to cater for most cases. -Users can provide a custom value to trade memory overhead for log -accuracy if they need to. -.SS Decorations -.PP -Logging messages are decorated with information about the message. -You can configure each output to use a custom set of decorators. -The order of the output is always the same as listed in the table. -You can configure the decorations to be used at run time. -Decorations are prepended to the log message. -For example: -.IP -.nf -\f[CB] -[6.567s][info][gc,old] Old collection complete -\f[R] -.fi -.PP -Omitting \f[V]decorators\f[R] defaults to \f[V]uptime\f[R], -\f[V]level\f[R], and \f[V]tags\f[R]. -The \f[V]none\f[R] decorator is special and is used to turn off all -decorations. -.PP -\f[V]time\f[R] (\f[V]t\f[R]), \f[V]utctime\f[R] (\f[V]utc\f[R]), -\f[V]uptime\f[R] (\f[V]u\f[R]), \f[V]timemillis\f[R] (\f[V]tm\f[R]), -\f[V]uptimemillis\f[R] (\f[V]um\f[R]), \f[V]timenanos\f[R] -(\f[V]tn\f[R]), \f[V]uptimenanos\f[R] (\f[V]un\f[R]), \f[V]hostname\f[R] -(\f[V]hn\f[R]), \f[V]pid\f[R] (\f[V]p\f[R]), \f[V]tid\f[R] -(\f[V]ti\f[R]), \f[V]level\f[R] (\f[V]l\f[R]), \f[V]tags\f[R] -(\f[V]tg\f[R]) decorators can also be specified as \f[V]none\f[R] for no -decoration. -.PP -Logging Messages Decorations -.TS -tab(@); -lw(14.9n) lw(55.1n). -T{ -Decorations -T}@T{ -Description -T} -_ -T{ -\f[V]time\f[R] or \f[V]t\f[R] -T}@T{ -Current time and date in ISO-8601 format. -T} -T{ -\f[V]utctime\f[R] or \f[V]utc\f[R] -T}@T{ -Universal Time Coordinated or Coordinated Universal Time. -T} -T{ -\f[V]uptime\f[R] or \f[V]u\f[R] -T}@T{ -Time since the start of the JVM in seconds and milliseconds. -For example, 6.567s. -T} -T{ -\f[V]timemillis\f[R] or \f[V]tm\f[R] -T}@T{ -The same value as generated by \f[V]System.currentTimeMillis()\f[R] -T} -T{ -\f[V]uptimemillis\f[R] or \f[V]um\f[R] -T}@T{ -Milliseconds since the JVM started. -T} -T{ -\f[V]timenanos\f[R] or \f[V]tn\f[R] -T}@T{ -The same value generated by \f[V]System.nanoTime()\f[R]. -T} -T{ -\f[V]uptimenanos\f[R] or \f[V]un\f[R] -T}@T{ -Nanoseconds since the JVM started. -T} -T{ -\f[V]hostname\f[R] or \f[V]hn\f[R] -T}@T{ -The host name. -T} -T{ -\f[V]pid\f[R] or \f[V]p\f[R] -T}@T{ -The process identifier. -T} -T{ -\f[V]tid\f[R] or \f[V]ti\f[R] -T}@T{ -The thread identifier. -T} -T{ -\f[V]level\f[R] or \f[V]l\f[R] -T}@T{ -The level associated with the log message. -T} -T{ -\f[V]tags\f[R] or \f[V]tg\f[R] -T}@T{ -The tag-set associated with the log message. -T} -.TE -.SS Convert GC Logging Flags to Xlog -.PP -Legacy GC Logging Flags to Xlog Configuration Mapping -.TS -tab(@); -lw(22.4n) lw(16.5n) lw(31.2n). -T{ -Legacy Garbage Collection (GC) Flag -T}@T{ -Xlog Configuration -T}@T{ -Comment -T} -_ -T{ -\f[V]G1PrintHeapRegions\f[R] -T}@T{ -\f[V]-Xlog:gc+region=trace\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]GCLogFileSize\f[R] -T}@T{ -No configuration available -T}@T{ -Log rotation is handled by the framework. -T} -T{ -\f[V]NumberOfGCLogFiles\f[R] -T}@T{ -Not Applicable -T}@T{ -Log rotation is handled by the framework. -T} -T{ -\f[V]PrintAdaptiveSizePolicy\f[R] -T}@T{ -\f[V]-Xlog:gc+ergo*=\f[R]\f[I]level\f[R] -T}@T{ -Use a \f[I]level\f[R] of \f[V]debug\f[R] for most of the information, or -a \f[I]level\f[R] of \f[V]trace\f[R] for all of what was logged for -\f[V]PrintAdaptiveSizePolicy\f[R]. -T} -T{ -\f[V]PrintGC\f[R] -T}@T{ -\f[V]-Xlog:gc\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]PrintGCApplicationConcurrentTime\f[R] -T}@T{ -\f[V]-Xlog:safepoint\f[R] -T}@T{ -Note that \f[V]PrintGCApplicationConcurrentTime\f[R] and -\f[V]PrintGCApplicationStoppedTime\f[R] are logged on the same tag and -aren\[aq]t separated in the new logging. -T} -T{ -\f[V]PrintGCApplicationStoppedTime\f[R] -T}@T{ -\f[V]-Xlog:safepoint\f[R] -T}@T{ -Note that \f[V]PrintGCApplicationConcurrentTime\f[R] and -\f[V]PrintGCApplicationStoppedTime\f[R] are logged on the same tag and -not separated in the new logging. -T} -T{ -\f[V]PrintGCCause\f[R] -T}@T{ -Not Applicable -T}@T{ -GC cause is now always logged. -T} -T{ -\f[V]PrintGCDateStamps\f[R] -T}@T{ -Not Applicable -T}@T{ -Date stamps are logged by the framework. -T} -T{ -\f[V]PrintGCDetails\f[R] -T}@T{ -\f[V]-Xlog:gc*\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]PrintGCID\f[R] -T}@T{ -Not Applicable -T}@T{ -GC ID is now always logged. -T} -T{ -\f[V]PrintGCTaskTimeStamps\f[R] -T}@T{ -\f[V]-Xlog:gc+task*=debug\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]PrintGCTimeStamps\f[R] -T}@T{ -Not Applicable -T}@T{ -Time stamps are logged by the framework. -T} -T{ -\f[V]PrintHeapAtGC\f[R] -T}@T{ -\f[V]-Xlog:gc+heap=trace\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]PrintReferenceGC\f[R] -T}@T{ -\f[V]-Xlog:gc+ref*=debug\f[R] -T}@T{ -Note that in the old logging, \f[V]PrintReferenceGC\f[R] had an effect -only if \f[V]PrintGCDetails\f[R] was also enabled. -T} -T{ -\f[V]PrintStringDeduplicationStatistics\f[R] -T}@T{ -\[ga]-Xlog:gc+stringdedup*=debug -T}@T{ -\[ga] Not Applicable -T} -T{ -\f[V]PrintTenuringDistribution\f[R] -T}@T{ -\f[V]-Xlog:gc+age*=\f[R]\f[I]level\f[R] -T}@T{ -Use a \f[I]level\f[R] of \f[V]debug\f[R] for the most relevant -information, or a \f[I]level\f[R] of \f[V]trace\f[R] for all of what was -logged for \f[V]PrintTenuringDistribution\f[R]. -T} -T{ -\f[V]UseGCLogFileRotation\f[R] -T}@T{ -Not Applicable -T}@T{ -What was logged for \f[V]PrintTenuringDistribution\f[R]. -T} -.TE -.SS Convert Runtime Logging Flags to Xlog -.PP -These legacy flags are no longer recognized and will cause an error if -used directly. -Use their unified logging equivalent instead. -.PP -Runtime Logging Flags to Xlog Configuration Mapping -.TS -tab(@); -lw(15.0n) lw(20.2n) lw(34.7n). -T{ -Legacy Runtime Flag -T}@T{ -Xlog Configuration -T}@T{ -Comment -T} -_ -T{ -\f[V]TraceExceptions\f[R] -T}@T{ -\f[V]-Xlog:exceptions=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassLoading\f[R] -T}@T{ -\f[V]-Xlog:class+load=\f[R]\f[I]level\f[R] -T}@T{ -Use \f[I]level\f[R]=\f[V]info\f[R] for regular information, or -\f[I]level\f[R]=\f[V]debug\f[R] for additional information. -In Unified Logging syntax, \f[V]-verbose:class\f[R] equals -\f[V]-Xlog:class+load=info,class+unload=info\f[R]. -T} -T{ -\f[V]TraceClassLoadingPreorder\f[R] -T}@T{ -\f[V]-Xlog:class+preorder=debug\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassUnloading\f[R] -T}@T{ -\f[V]-Xlog:class+unload=\f[R]\f[I]level\f[R] -T}@T{ -Use \f[I]level\f[R]=\f[V]info\f[R] for regular information, or -\f[I]level\f[R]=\f[V]trace\f[R] for additional information. -In Unified Logging syntax, \f[V]-verbose:class\f[R] equals -\f[V]-Xlog:class+load=info,class+unload=info\f[R]. -T} -T{ -\f[V]VerboseVerification\f[R] -T}@T{ -\f[V]-Xlog:verification=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassPaths\f[R] -T}@T{ -\f[V]-Xlog:class+path=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassResolution\f[R] -T}@T{ -\f[V]-Xlog:class+resolve=debug\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassInitialization\f[R] -T}@T{ -\f[V]-Xlog:class+init=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceLoaderConstraints\f[R] -T}@T{ -\f[V]-Xlog:class+loader+constraints=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceClassLoaderData\f[R] -T}@T{ -\f[V]-Xlog:class+loader+data=\f[R]\f[I]level\f[R] -T}@T{ -Use \f[I]level\f[R]=\f[V]debug\f[R] for regular information or -\f[I]level\f[R]=\f[V]trace\f[R] for additional information. -T} -T{ -\f[V]TraceSafepointCleanupTime\f[R] -T}@T{ -\f[V]-Xlog:safepoint+cleanup=info\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceSafepoint\f[R] -T}@T{ -\f[V]-Xlog:safepoint=debug\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceMonitorInflation\f[R] -T}@T{ -\f[V]-Xlog:monitorinflation=debug\f[R] -T}@T{ -Not Applicable -T} -T{ -\f[V]TraceRedefineClasses\f[R] -T}@T{ -\f[V]-Xlog:redefine+class*=\f[R]\f[I]level\f[R] -T}@T{ -\f[I]level\f[R]=\f[V]info\f[R], \f[V]debug\f[R], and \f[V]trace\f[R] -provide increasing amounts of information. -T} -.TE -.SS -Xlog Usage Examples -.PP -The following are \f[V]-Xlog\f[R] examples. -.TP -\f[V]-Xlog\f[R] -Logs all messages by using the \f[V]info\f[R] level to \f[V]stdout\f[R] -with \f[V]uptime\f[R], \f[V]levels\f[R], and \f[V]tags\f[R] decorations. -This is equivalent to using: -.RS -.RS -.PP -\f[V]-Xlog:all=info:stdout:uptime,levels,tags\f[R] -.RE -.RE -.TP -\f[V]-Xlog:gc\f[R] -Logs messages tagged with the \f[V]gc\f[R] tag using \f[V]info\f[R] -level to \f[V]stdout\f[R]. -The default configuration for all other messages at level -\f[V]warning\f[R] is in effect. -.TP -\f[V]-Xlog:gc,safepoint\f[R] -Logs messages tagged either with the \f[V]gc\f[R] or \f[V]safepoint\f[R] -tags, both using the \f[V]info\f[R] level, to \f[V]stdout\f[R], with -default decorations. -Messages tagged with both \f[V]gc\f[R] and \f[V]safepoint\f[R] won\[aq]t -be logged. -.TP -\f[V]-Xlog:gc+ref=debug\f[R] -Logs messages tagged with both \f[V]gc\f[R] and \f[V]ref\f[R] tags, -using the \f[V]debug\f[R] level to \f[V]stdout\f[R], with default -decorations. -Messages tagged only with one of the two tags won\[aq]t be logged. -.TP -\f[V]-Xlog:gc=debug:file=gc.txt:none\f[R] -Logs messages tagged with the \f[V]gc\f[R] tag using the \f[V]debug\f[R] -level to a file called \f[V]gc.txt\f[R] with no decorations. -The default configuration for all other messages at level -\f[V]warning\f[R] is still in effect. -.TP -\f[V]-Xlog:gc=trace:file=gctrace.txt:uptimemillis,pid:filecount=5,filesize=1024\f[R] -Logs messages tagged with the \f[V]gc\f[R] tag using the \f[V]trace\f[R] -level to a rotating file set with 5 files with size 1 MB with the base -name \f[V]gctrace.txt\f[R] and uses decorations \f[V]uptimemillis\f[R] -and \f[V]pid\f[R]. -.RS -.PP -The default configuration for all other messages at level -\f[V]warning\f[R] is still in effect. -.RE -.TP -\f[V]-Xlog:gc::uptime,tid\f[R] -Logs messages tagged with the \f[V]gc\f[R] tag using the default -\[aq]info\[aq] level to default the output \f[V]stdout\f[R] and uses -decorations \f[V]uptime\f[R] and \f[V]tid\f[R]. -The default configuration for all other messages at level -\f[V]warning\f[R] is still in effect. -.TP -\f[V]-Xlog:gc*=info,safepoint*=off\f[R] -Logs messages tagged with at least \f[V]gc\f[R] using the \f[V]info\f[R] -level, but turns off logging of messages tagged with -\f[V]safepoint\f[R]. -Messages tagged with both \f[V]gc\f[R] and \f[V]safepoint\f[R] won\[aq]t -be logged. -.TP -\f[V]-Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt\f[R] -Turns off all logging, including warnings and errors, and then enables -messages tagged with \f[V]safepoint\f[R]using \f[V]trace\f[R]level to -the file \f[V]safepointtrace.txt\f[R]. -The default configuration doesn\[aq]t apply, because the command line -started with \f[V]-Xlog:disable\f[R]. -.SS Complex -Xlog Usage Examples -.PP -The following describes a few complex examples of using the -\f[V]-Xlog\f[R] option. -.TP -\f[V]-Xlog:gc+class*=debug\f[R] -Logs messages tagged with at least \f[V]gc\f[R] and \f[V]class\f[R] tags -using the \f[V]debug\f[R] level to \f[V]stdout\f[R]. -The default configuration for all other messages at the level -\f[V]warning\f[R] is still in effect -.TP -\f[V]-Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt\f[R] -Logs messages tagged with at least the \f[V]gc\f[R] and \f[V]meta\f[R] -tags using the \f[V]trace\f[R] level to the file \f[V]metatrace.txt\f[R] -but turns off all messages tagged with \f[V]class\f[R]. -Messages tagged with \f[V]gc\f[R], \f[V]meta\f[R], and \f[V]class\f[R] -aren\[aq]t be logged as \f[V]class*\f[R] is set to off. -The default configuration for all other messages at level -\f[V]warning\f[R] is in effect except for those that include -\f[V]class\f[R]. -.TP -\f[V]-Xlog:gc+meta=trace\f[R] -Logs messages tagged with exactly the \f[V]gc\f[R] and \f[V]meta\f[R] -tags using the \f[V]trace\f[R] level to \f[V]stdout\f[R]. -The default configuration for all other messages at level -\f[V]warning\f[R] is still be in effect. -.TP -\f[V]-Xlog:gc+class+heap*=debug,meta*=warning,threads*=off\f[R] -Logs messages tagged with at least \f[V]gc\f[R], \f[V]class\f[R], and -\f[V]heap\f[R] tags using the \f[V]trace\f[R] level to \f[V]stdout\f[R] -but only log messages tagged with \f[V]meta\f[R] with level. -The default configuration for all other messages at the level -\f[V]warning\f[R] is in effect except for those that include -\f[V]threads\f[R]. -.SH VALIDATE JAVA VIRTUAL MACHINE FLAG ARGUMENTS -.PP -You use values provided to all Java Virtual Machine (JVM) command-line -flags for validation and, if the input value is invalid or out-of-range, -then an appropriate error message is displayed. -.PP -Whether they\[aq]re set ergonomically, in a command line, by an input -tool, or through the APIs (for example, classes contained in the package -\f[V]java.lang.management\f[R]) the values provided to all Java Virtual -Machine (JVM) command-line flags are validated. -Ergonomics are described in Java Platform, Standard Edition HotSpot -Virtual Machine Garbage Collection Tuning Guide. -.PP -Range and constraints are validated either when all flags have their -values set during JVM initialization or a flag\[aq]s value is changed -during runtime (for example using the \f[V]jcmd\f[R] tool). -The JVM is terminated if a value violates either the range or constraint -check and an appropriate error message is printed on the error stream. -.PP -For example, if a flag violates a range or a constraint check, then the -JVM exits with an error: -.IP -.nf -\f[CB] -java -XX:AllocatePrefetchStyle=5 -version -intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ] -Improperly specified VM option \[aq]AllocatePrefetchStyle=5\[aq] -Error: Could not create the Java Virtual Machine. -Error: A fatal exception has occurred. Program will exit. -\f[R] -.fi -.PP -The flag \f[V]-XX:+PrintFlagsRanges\f[R] prints the range of all the -flags. -This flag allows automatic testing of the flags by the values provided -by the ranges. -For the flags that have the ranges specified, the type, name, and the -actual range is printed in the output. -.PP -For example, -.IP -.nf -\f[CB] -intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product} -\f[R] -.fi -.PP -For the flags that don\[aq]t have the range specified, the values -aren\[aq]t displayed in the print out. -For example: -.IP -.nf -\f[CB] -size_t NewSize [ ... ] {product} -\f[R] -.fi -.PP -This helps to identify the flags that need to be implemented. -The automatic testing framework can skip those flags that don\[aq]t have -values and aren\[aq]t implemented. -.SH LARGE PAGES -.PP -You use large pages, also known as huge pages, as memory pages that are -significantly larger than the standard memory page size (which varies -depending on the processor and operating system). -Large pages optimize processor Translation-Lookaside Buffers. -.PP -A Translation-Lookaside Buffer (TLB) is a page translation cache that -holds the most-recently used virtual-to-physical address translations. -A TLB is a scarce system resource. -A TLB miss can be costly because the processor must then read from the -hierarchical page table, which may require multiple memory accesses. -By using a larger memory page size, a single TLB entry can represent a -larger memory range. -This results in less pressure on a TLB, and memory-intensive -applications may have better performance. -.PP -However, using large pages can negatively affect system performance. -For example, when a large amount of memory is pinned by an application, -it may create a shortage of regular memory and cause excessive paging in -other applications and slow down the entire system. -Also, a system that has been up for a long time could produce excessive -fragmentation, which could make it impossible to reserve enough large -page memory. -When this happens, either the OS or JVM reverts to using regular pages. -.PP -Linux and Windows support large pages. -.SS Large Pages Support for Linux -.PP -Linux supports large pages since version 2.6. -To check if your environment supports large pages, try the following: -.IP -.nf -\f[CB] -# cat /proc/meminfo | grep Huge -HugePages_Total: 0 -HugePages_Free: 0 -\&... -Hugepagesize: 2048 kB -\f[R] -.fi -.PP -If the output contains items prefixed with \[dq]Huge\[dq], then your -system supports large pages. -The values may vary depending on environment. -The \f[V]Hugepagesize\f[R] field shows the default large page size in -your environment, and the other fields show details for large pages of -this size. -Newer kernels have support for multiple large page sizes. -To list the supported page sizes, run this: -.IP -.nf -\f[CB] -# ls /sys/kernel/mm/hugepages/ -hugepages-1048576kB hugepages-2048kB -\f[R] -.fi -.PP -The above environment supports 2 MB and 1 GB large pages, but they need -to be configured so that the JVM can use them. -When using large pages and not enabling transparent huge pages (option -\f[V]-XX:+UseTransparentHugePages\f[R]), the number of large pages must -be pre-allocated. -For example, to enable 8 GB of memory to be backed by 2 MB large pages, -login as \f[V]root\f[R] and run: -.RS -.PP -\f[V]# echo 4096 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages\f[R] -.RE -.PP -It is always recommended to check the value of \f[V]nr_hugepages\f[R] -after the request to make sure the kernel was able to allocate the -requested number of large pages. -.RS -.PP -\f[B]Note:\f[R] The values contained in \f[V]/proc\f[R] and -\f[V]/sys\f[R] reset after you reboot your system, so may want to set -them in an initialization script (for example, \f[V]rc.local\f[R] or -\f[V]sysctl.conf\f[R]). -.RE -.PP -If you configure the OS kernel parameters to enable use of large pages, -the Java processes may allocate large pages for the Java heap as well as -other internal areas, for example: -.IP \[bu] 2 -Code cache -.IP \[bu] 2 -Marking bitmaps -.PP -Consequently, if you configure the \f[V]nr_hugepages\f[R] parameter to -the size of the Java heap, then the JVM can still fail to allocate the -heap using large pages because other areas such as the code cache might -already have used some of the configured large pages. -.SS Large Pages Support for Windows -.PP -To use large pages support on Windows, the administrator must first -assign additional privileges to the user who is running the application: -.IP "1." 3 -Select \f[B]Control Panel\f[R], \f[B]Administrative Tools\f[R], and then -\f[B]Local Security Policy\f[R]. -.IP "2." 3 -Select \f[B]Local Policies\f[R] and then \f[B]User Rights -Assignment\f[R]. -.IP "3." 3 -Double-click \f[B]Lock pages in memory\f[R], then add users and/or -groups. -.IP "4." 3 -Reboot your system. -.PP -Note that these steps are required even if it\[aq]s the administrator -who\[aq]s running the application, because administrators by default -don\[aq]t have the privilege to lock pages in memory. -.SH APPLICATION CLASS DATA SHARING -.PP -Application Class Data Sharing (AppCDS) stores classes used by your -applications in an archive file. -Since these classes are stored in a format that can be loaded very -quickly (compared to classes stored in a JAR file), AppCDS can improve -the start-up time of your applications. -In addition, AppCDS can reduce the runtime memory footprint by sharing -parts of these classes across multiple processes. -.PP -Classes in the CDS archive are stored in an optimized format that\[aq]s -about 2 to 5 times larger than classes stored in JAR files or the JDK -runtime image. -Therefore, it\[aq]s a good idea to archive only those classes that are -actually used by your application. -These usually are just a small portion of all available classes. -For example, your application may use only a few APIs provided by a -large library. -.SS Using CDS Archives -.PP -By default, in most JDK distributions, unless \f[V]-Xshare:off\f[R] is -specified, the JVM starts up with a default CDS archive, which is -usually located in \f[V]JAVA_HOME/lib/server/classes.jsa\f[R] (or -\f[V]JAVA_HOME\[rs]bin\[rs]server\[rs]classes.jsa\f[R] on Windows). -This archive contains about 1300 core library classes that are used by -most applications. -.PP -To use CDS for the exact set of classes used by your application, you -can use the \f[V]-XX:SharedArchiveFile\f[R] option, which has the -general form: -.RS -.PP -\f[V]-XX:SharedArchiveFile=:\f[R] -.RE -.IP \[bu] 2 -The \f[V]\f[R] overrides the default CDS archive. -.IP \[bu] 2 -The \f[V]\f[R] provides additional classes that can be -loaded on top of those in the \f[V]\f[R]. -.IP \[bu] 2 -On Windows, the above path delimiter \f[V]:\f[R] should be replaced with -\f[V];\f[R] -.PP -(The names \[dq]static\[dq] and \[dq]dynamic\[dq] are used for -historical reasons. -The only significance is that the \[dq]static\[dq] archive is loaded -first and the \[dq]dynamic\[dq] archive is loaded second). -.PP -The JVM can use up to two archives. -To use only a single \f[V]\f[R], you can omit the -\f[V]\f[R] portion: -.RS -.PP -\f[V]-XX:SharedArchiveFile=\f[R] -.RE -.PP -For convenience, the \f[V]\f[R] records the location of -the \f[V]\f[R]. -Therefore, you can omit the \f[V]\f[R] by saying only: -.RS -.PP -\f[V]-XX:SharedArchiveFile=\f[R] -.RE -.SS Manually Creating CDS Archives -.PP -CDS archives can be created manually using several methods: -.IP \[bu] 2 -\f[V]-Xshare:dump\f[R] -.IP \[bu] 2 -\f[V]-XX:ArchiveClassesAtExit\f[R] -.IP \[bu] 2 -\f[V]jcmd VM.cds\f[R] -.PP -One common operation in all these methods is a \[dq]trial run\[dq], -where you run the application once to determine the classes that should -be stored in the archive. -.SS Creating a Static CDS Archive File with -Xshare:dump -.PP -The following steps create a static CDS archive file that contains all -the classes used by the \f[V]test.Hello\f[R] application. -.IP "1." 3 -Create a list of all classes used by the \f[V]test.Hello\f[R] -application. -The following command creates a file named \f[V]hello.classlist\f[R] -that contains a list of all classes used by this application: -.RS 4 -.RS -.PP -\f[V]java -Xshare:off -XX:DumpLoadedClassList=hello.classlist -cp hello.jar test.Hello\f[R] -.RE -.PP -The classpath specified by the \f[V]-cp\f[R] parameter must contain only -JAR files. -.RE -.IP "2." 3 -Create a static archive, named \f[V]hello.jsa\f[R], that contains all -the classes in \f[V]hello.classlist\f[R]: -.RS 4 -.RS -.PP -\f[V]java -Xshare:dump -XX:SharedArchiveFile=hello.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar\f[R] -.RE -.RE -.IP "3." 3 -Run the application \f[V]test.Hello\f[R] with the archive -\f[V]hello.jsa\f[R]: -.RS 4 -.RS -.PP -\f[V]java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hello\f[R] -.RE -.RE -.IP "4." 3 -\f[B]Optional\f[R] Verify that the \f[V]test.Hello\f[R] application is -using the class contained in the \f[V]hello.jsa\f[R] shared archive: -.RS 4 -.RS -.PP -\f[V]java -XX:SharedArchiveFile=hello.jsa -cp hello.jar -Xlog:class+load test.Hello\f[R] -.RE -.PP -The output of this command should contain the following text: -.RS -.PP -\f[V][info][class,load] test.Hello source: shared objects file\f[R] -.RE -.RE -.PP -By default, when the \f[V]-Xshare:dump\f[R] option is used, the JVM runs -in interpreter-only mode (as if the \f[V]-Xint\f[R] option were -specified). -This is required for generating deterministic output in the shared -archive file. -I.e., the exact same archive will be generated, bit-for-bit, every time -you dump it. -However, if deterministic output is not needed, and you have a large -classlist, you can explicitly add \f[V]-Xmixed\f[R] to the command-line -to enable the JIT compiler. -This will speed up the archive creation. -.SS Creating a Dynamic CDS Archive File with -XX:ArchiveClassesAtExit -.PP -Advantages of dynamic CDS archives are: -.IP \[bu] 2 -They usually use less disk space, since they don\[aq]t need to store the -classes that are already in the static archive. -.IP \[bu] 2 -They are created with one fewer step than the comparable static archive. -.PP -The following steps create a dynamic CDS archive file that contains the -classes that are used by the \f[V]test.Hello\f[R] application, excluding -those that are already in the default CDS archive. -.IP "1." 3 -Create a dynamic CDS archive, named \f[V]hello.jsa\f[R], that contains -all the classes in \f[V]hello.jar\f[R] loaded by the application -\f[V]test.Hello\f[R]: -.RS 4 -.RS -.PP -\f[V]java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello\f[R] -.RE -.RE -.IP "2." 3 -Run the application \f[V]test.Hello\f[R] with the shared archive -\f[V]hello.jsa\f[R]: -.RS 4 -.RS -.PP -\f[V]java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hello\f[R] -.RE -.RE -.IP "3." 3 -\f[B]Optional\f[R] Repeat step 4 of the previous section to verify that -the \f[V]test.Hello\f[R] application is using the class contained in the -\f[V]hello.jsa\f[R] shared archive. -.PP -It\[aq]s also possible to create a dynamic CDS archive with a -non-default static CDS archive. -E.g., -.RS -.PP -\f[V]java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello\f[R] -.RE -.PP -To run the application using this dynamic CDS archive: -.RS -.PP -\f[V]java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hello\f[R] -.RE -.PP -(On Windows, the above path delimiter \f[V]:\f[R] should be replaced -with \f[V];\f[R]) -.PP -As mention above, the name of the static archive can be skipped: -.RS -.PP -\f[V]java -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello\f[R] -.RE -.SS Creating CDS Archive Files with jcmd -.PP -The previous two sections require you to modify the application\[aq]s -start-up script in order to create a CDS archive. -Sometimes this could be difficult, for example, if the application\[aq]s -class path is set up by complex routines. -.PP -The \f[V]jcmd VM.cds\f[R] command provides a less intrusive way for -creating a CDS archive by connecting to a running JVM process. -You can create either a static: -.RS -.PP -\f[V]jcmd VM.cds static_dump my_static_archive.jsa\f[R] -.RE -.PP -or a dynamic archive: -.RS -.PP -\f[V]jcmd VM.cds dynamic_dump my_dynamic_archive.jsa\f[R] -.RE -.PP -To use the resulting archive file in a subsequent run of the application -without modifying the application\[aq]s start-up script, you can use the -following technique: -.RS -.PP -\f[V]env JAVA_TOOL_OPTIONS=-XX:SharedArchiveFile=my_static_archive.jsa bash app_start.sh\f[R] -.RE -.PP -Note: to use \f[V]jcmd VM.cds dynamic_dump\f[R], the JVM process -identified by \f[V]\f[R] must be started with -\f[V]-XX:+RecordDynamicDumpInfo\f[R], which can also be passed to the -application start-up script with the same technique: -.RS -.PP -\f[V]env JAVA_TOOL_OPTIONS=-XX:+RecordDynamicDumpInfo bash app_start.sh\f[R] -.RE -.SS Creating Dynamic CDS Archive File with -XX:+AutoCreateSharedArchive -.PP -\f[V]-XX:+AutoCreateSharedArchive\f[R] is a more convenient way of -creating/using CDS archives. -Unlike the methods of manual CDS archive creation described in the -previous section, with \f[V]-XX:+AutoCreateSharedArchive\f[R], it\[aq]s -no longer necessary to have a separate trial run. -Instead, you can always run the application with the same command-line -and enjoy the benefits of CDS automatically. -.RS -.PP -\f[V]java -XX:+AutoCreateSharedArchive -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello\f[R] -.RE -.PP -If the specified archive file exists and was created by the same version -of the JDK, then it will be loaded as a dynamic archive; otherwise it is -ignored at VM startup. -.PP -At VM exit, if the specified archive file does not exist, it will be -created. -If it exists but was created with a different (but post JDK 19) version -of the JDK, then it will be replaced. -In both cases the archive will be ready to be loaded the next time the -JVM is launched with the same command line. -.PP -If the specified archive file exists but was created by a JDK version -prior to JDK 19, then it will be ignored: neither loaded at startup, nor -replaced at exit. -.PP -Developers should note that the contents of the CDS archive file are -specific to each build of the JDK. -Therefore, if you switch to a different JDK build, -\f[V]-XX:+AutoCreateSharedArchive\f[R] will automatically recreate the -archive to match the JDK. -If you intend to use this feature with an existing archive, you should -make sure that the archive is created by at least version 19 of the JDK. -.SS Restrictions on Class Path and Module Path -.IP \[bu] 2 -Neither the class path (\f[V]-classpath\f[R] and -\f[V]-Xbootclasspath/a\f[R]) nor the module path -(\f[V]--module-path\f[R]) can contain non-empty directories. -.IP \[bu] 2 -Only modular JAR files are supported in \f[V]--module-path\f[R]. -Exploded modules are not supported. -.IP \[bu] 2 -The class path used at archive creation time must be the same as (or a -prefix of) the class path used at run time. -(There\[aq]s no such requirement for the module path.) -.IP \[bu] 2 -The CDS archive cannot be loaded if any JAR files in the class path or -module path are modified after the archive is generated. -.IP \[bu] 2 -If any of the VM options \f[V]--upgrade-module-path\f[R], -\f[V]--patch-module\f[R] or \f[V]--limit-modules\f[R] are specified, CDS -is disabled. -This means that the JVM will execute without loading any CDS archives. -In addition, if you try to create a CDS archive with any of these 3 -options specified, the JVM will report an error. -.SH PERFORMANCE TUNING EXAMPLES -.PP -You can use the Java advanced runtime options to optimize the -performance of your applications. -.SS Tuning for Higher Throughput -.PP -Use the following commands and advanced options to achieve higher -throughput performance for your application: -.RS -.PP -\f[V]java -server -XX:+UseParallelGC -XX:+UseLargePages -Xmn10g -Xms26g -Xmx26g\f[R] -.RE -.SS Tuning for Lower Response Time -.PP -Use the following commands and advanced options to achieve lower -response times for your application: -.RS -.PP -\f[V]java -XX:+UseG1GC -XX:MaxGCPauseMillis=100\f[R] -.RE -.SS Keeping the Java Heap Small and Reducing the Dynamic Footprint of Embedded Applications -.PP -Use the following advanced runtime options to keep the Java heap small -and reduce the dynamic footprint of embedded applications: -.RS -.PP -\f[V]-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5\f[R] -.RE -.RS -.PP -\f[B]Note:\f[R] The defaults for these two options are 70% and 40% -respectively. -Because performance sacrifices can occur when using these small -settings, you should optimize for a small footprint by reducing these -settings as much as possible without introducing unacceptable -performance degradation. -.RE -.SH EXIT STATUS -.PP -The following exit values are typically returned by the launcher when -the launcher is called with the wrong arguments, serious errors, or -exceptions thrown by the JVM. -However, a Java application may choose to return any value by using the -API call \f[V]System.exit(exitValue)\f[R]. -The values are: -.IP \[bu] 2 -\f[V]0\f[R]: Successful completion -.IP \[bu] 2 -\f[V]>0\f[R]: An error occurred diff --git a/src/java.base/share/man/java.md b/src/java.base/share/man/java.md new file mode 100644 index 00000000000..f79e55622cd --- /dev/null +++ b/src/java.base/share/man/java.md @@ -0,0 +1,4050 @@ +--- +# Copyright (c) 1994, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JAVA(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +java - launch a Java application + +## Synopsis + +To launch a class file: + +`java` \[*options*\] *mainclass* \[*args* ...\] + +To launch the main class in a JAR file: + +`java` \[*options*\] `-jar` *jarfile* \[*args* ...\] + +To launch the main class in a module: + +`java` \[*options*\] `-m` *module*\[`/`*mainclass*\] \[*args* ...\] + +or + +`java` \[*options*\] `--module` *module*\[`/`*mainclass*\] \[*args* ...\] + +To launch a source-file program: + +`java` \[*options*\] *source-file* \[*args* ...\] + +*options* +: Optional: Specifies command-line options separated by spaces. See [Overview + of Java Options] for a description of available + options. + +*mainclass* +: Specifies the name of the class to be launched. Command-line entries + following `classname` are the arguments for the main method. + +`-jar` *jarfile* +: Executes a program encapsulated in a JAR file. The *jarfile* argument is + the name of a JAR file with a manifest that contains a line in the form + `Main-Class:`*classname* that defines the class with the + `public static void main(String[] args)` method that serves as your + application's starting point. When you use `-jar`, the specified JAR file + is the source of all user classes, and other class path settings are + ignored. If you're using JAR files, then see [jar](jar.html). + +`-m` or `--module` *module*\[`/`*mainclass*\] +: Executes the main class in a module specified by *mainclass* if it is + given, or, if it is not given, the value in the *module*. In other words, + *mainclass* can be used when it is not specified by the module, or to + override the value when it is specified. + + See [Standard Options for Java]. + +*source-file* +: Only used to launch a source-file program. Specifies the source file + that contains the main class when using source-file mode. See [Using + Source-File Mode to Launch Source-Code Programs] + +*args* ... +: Optional: Arguments following *mainclass*, *source-file*, `-jar` *jarfile*, + and `-m` or `--module` *module*`/`*mainclass* are passed as arguments to + the main class. + +## Description + +The `java` command starts a Java application. It does this by starting the Java +Virtual Machine (JVM), loading the specified class, and calling that +class's `main()` method. The method must be declared `public` and `static`, it +must not return any value, and it must accept a `String` array as a parameter. +The method declaration has the following form: + +> `public static void main(String[] args)` + +In source-file mode, the `java` command can launch a class declared in a source +file. See [Using Source-File Mode to Launch Source-Code Programs] +for a description of using the source-file mode. + +> **Note:** You can use the `JDK_JAVA_OPTIONS` launcher environment variable to prepend its +content to the actual command line of the `java` launcher. See [Using the +JDK\_JAVA\_OPTIONS Launcher Environment Variable]. + +By default, the first argument that isn't an option of the `java` command is +the fully qualified name of the class to be called. If `-jar` is specified, +then its argument is the name of the JAR file containing class and resource +files for the application. The startup class must be indicated by the +`Main-Class` manifest header in its manifest file. + +Arguments after the class file name or the JAR file name are passed to the +`main()` method. + +### `javaw` + +**Windows:** The `javaw` command is identical to `java`, except that with +`javaw` there's no associated console window. Use `javaw` when you don't want a +command prompt window to appear. The `javaw` launcher will, however, display a +dialog box with error information if a launch fails. + +## Using Source-File Mode to Launch Source-Code Programs + +To launch a class declared in a source file, run the `java` launcher in +source-file mode. Entering source-file mode is determined by two items on the +`java` command line: + +- The first item on the command line that is not an option or part of an + option. In other words, the item in the command line that would otherwise + be the main class name. + +- The `--source` *version* option, if present. + +If the class identifies an existing file that has a `.java` extension, or if +the `--source` option is specified, then source-file mode is selected. The +source file is then compiled and run. The `--source` option can be used to +specify the source *version* or *N* of the source code. This determines the API +that can be used. When you set `--source` *N*, you can only use the public API +that was defined in JDK *N*. + +> **Note:** The valid values of *N* change for each release, with new values added and old +values removed. You'll get an error message if you use a value of *N* that is +no longer supported. +The supported values of *N* are the current Java SE release (`@@VERSION_SPECIFICATION@@`) +and a limited number of previous releases, detailed in the command-line help +for `javac`, under the `--source` and `--release` options. + +If the file does not have the `.java` extension, the `--source` option must be +used to tell the `java` command to use the source-file mode. The `--source` +option is used for cases when the source file is a "script" to be executed and +the name of the source file does not follow the normal naming conventions for +Java source files. + +In source-file mode, the effect is as though the source file is compiled into +memory, and the first class found in the source file is executed. Any arguments +placed after the name of the source file in the original command line are +passed to the compiled class when it is executed. + +For example, if a file were named `HelloWorld.java` and contained a class named +`HelloWorld`, then the source-file mode command to launch the class would be: + +> `java HelloWorld.java` + +This use of source-file mode is informally equivalent to using the following two +commands: + +``` +javac -d --source-path HelloWorld.java +java --class-path HelloWorld +``` + +where `` is computed + +**In source-file mode, any additional command-line options are processed as +follows:** + +- The launcher scans the options specified before the source file for any + that are relevant in order to compile the source file. + + This includes: `--class-path`, `--module-path`, `--add-exports`, + `--add-modules`, `--limit-modules`, `--patch-module`, + `--upgrade-module-path`, and any variant forms of those options. It also + includes the new `--enable-preview` option, described in JEP 12. + +- No provision is made to pass any additional options to the compiler, such + as `-processor` or `-Werror`. + +- Command-line argument files (`@`-files) may be used in the standard way. + Long lists of arguments for either the VM or the program being invoked may + be placed in files specified on the command-line by prefixing the filename + with an `@` character. + +**In source-file mode, compilation proceeds as follows:** + +- Any command-line options that are relevant to the compilation environment + are taken into account. These include: `--class-path`/`-classpath`/`-cp`, + `--module-path`/`-p`, `--add-exports`, `--add-modules`, `--limit-modules`, + `--patch-module`, `--upgrade-module-path`, `--enable-preview`. + +- The root of the source tree, `` is computed from the package + of the class being launched. For example, if `HelloWorld.java` declared its classes + to be in the `hello` package, then the file `HelloWorld.java` is expected + to reside in the directory `somedir/hello/`. In this case, `somedir` is + computed to be the root of the source tree. + +- The root of the source tree serves as the source-path for compilation, so that + other source files found in that tree and are needed by `HelloWorld` could be + compiled. + +- Annotation processing is disabled, as if `-proc:none` is in effect. + +- If a version is specified, via the `--source` option, the value is used as + the argument for an implicit `--release` option for the compilation. This + sets both the source version accepted by compiler and the system API that + may be used by the code in the source file. + +- If `--enable-preview` is specified, the `--source N` arguments can be omitted. + If the Java runtime version is `N`, then `--release N` is implied when + compiling source files. + +- If a `module-info.java` file exists in the `` directory, its + module declaration is used to define a named module that will contain all + the classes compiled from `.java` files in the source tree. If + `module-info.java` does not exist, all the classes compiled from source files + will be compiled in the context of the unnamed module. + +- The source file that is launched should contain one or more top-level classes, the first of + which is taken as the class to be executed. + +- For the source file that is launched, the compiler does not enforce the optional restriction defined at the end + of JLS 7.6, that a type in a named package should exist in a file whose + name is composed from the type name followed by the `.java` extension. + +- If a source file contains errors, appropriate error messages are written + to the standard error stream, and the launcher exits with a non-zero exit + code. + +**In source-file mode, execution proceeds as follows:** + +- The class to be executed is the first top-level class found in the source + file. It must contain a declaration of an entry `main` method. + +- The compiled classes are loaded by a custom class loader, that delegates to + the application class loader. This implies that classes appearing on the + application class path cannot refer to any classes declared in source files. + +- If a `module-info.java` file exists in the `` directory, then all + the classes compiled from `.java` files in the source tree will be in that + module, which will serve as the root module for the execution of the program. + If `module-info.java` does not exist, the compiled classes are executed in the + context of an unnamed module, as though `--add-modules=ALL-DEFAULT` is in effect. + This is in addition to any other `--add-module` options that may be have been + specified on the command line. + +- Any arguments appearing after the name of the file on the command line are + passed to the main method in the obvious way. + +- It is an error if there is a class on the application class path whose name + is the same as that of the class to be executed. + +See [JEP 458: Launch Multi-File Source-Code Programs]( +https://openjdk.org/jeps/458) for complete details. + +## Using the JDK\_JAVA\_OPTIONS Launcher Environment Variable + +`JDK_JAVA_OPTIONS` prepends its content to the options parsed from the command +line. The content of the `JDK_JAVA_OPTIONS` environment variable is a list of +arguments separated by white-space characters (as determined by `isspace()`). +These are prepended to the command line arguments passed to `java` launcher. +The encoding requirement for the environment variable is the same as the `java` +command line on the system. `JDK_JAVA_OPTIONS` environment variable content is +treated in the same manner as that specified in the command line. + +Single (`'`) or double (`"`) quotes can be used to enclose arguments that +contain whitespace characters. All content between the open quote and the +first matching close quote are preserved by simply removing the pair of quotes. +In case a matching quote is not found, the launcher will abort with an error +message. `@`-files are supported as they are specified in the command line. +However, as in `@`-files, use of a wildcard is not supported. In order to +mitigate potential misuse of `JDK_JAVA_OPTIONS` behavior, options that specify +the main class (such as `-jar`) or cause the `java` launcher to exit without +executing the main class (such as `-h`) are disallowed in the environment +variable. If any of these options appear in the environment variable, the +launcher will abort with an error message. When `JDK_JAVA_OPTIONS` is set, the +launcher prints a message to stderr as a reminder. + +**Example:** + +``` +$ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"' +$ java -Xint @file3 +``` + +is equivalent to the command line: + +``` +java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3 +``` + +## Overview of Java Options + +The `java` command supports a wide range of options in the following +categories: + +- [Standard Options for Java]\: Options guaranteed to be supported by all + implementations of the Java Virtual Machine (JVM). They're used for common + actions, such as checking the version of the JRE, setting the class path, + enabling verbose output, and so on. + +- [Extra Options for Java]\: General purpose options that are specific to the + Java HotSpot Virtual Machine. They aren't guaranteed to be supported by + all JVM implementations, and are subject to change. These options start + with `-X`. + +The advanced options aren't recommended for casual use. These are developer +options used for tuning specific areas of the Java HotSpot Virtual Machine +operation that often have specific system requirements and may require +privileged access to system configuration parameters. Several examples of +performance tuning are provided in [Performance Tuning Examples]. These +options aren't guaranteed to be supported by all JVM implementations and are +subject to change. Advanced options start with `-XX`. + +- [Advanced Runtime Options for Java]\: Control the runtime behavior of the + Java HotSpot VM. + +- [Advanced JIT Compiler Options for java]\: Control the dynamic just-in-time + (JIT) compilation performed by the Java HotSpot VM. + +- [Advanced Serviceability Options for Java]\: Enable gathering system + information and performing extensive debugging. + +- [Advanced Garbage Collection Options for Java]\: Control how garbage + collection (GC) is performed by the Java HotSpot + +Boolean options are used to either enable a feature that's disabled by default +or disable a feature that's enabled by default. Such options don't require a +parameter. Boolean `-XX` options are enabled using the plus sign +(`-XX:+`*OptionName*) and disabled using the minus sign (`-XX:-`*OptionName*). + +For options that require an argument, the argument may be separated from the +option name by a space, a colon (:), or an equal sign (=), or the argument may +directly follow the option (the exact syntax differs for each option). If +you're expected to specify the size in bytes, then you can use no suffix, or +use the suffix `k` or `K` for kilobytes (KB), `m` or `M` for megabytes (MB), or +`g` or `G` for gigabytes (GB). For example, to set the size to 8 GB, you can +specify either `8g`, `8192m`, `8388608k`, or `8589934592` as the argument. If +you are expected to specify the percentage, then use a number from 0 to 1. For +example, specify `0.25` for 25%. + +The following sections describe the options that are deprecated, obsolete, and +removed: + +- [Deprecated Java Options]\: Accepted and acted upon --- a warning is issued + when they're used. + +- [Obsolete Java Options]\: Accepted but ignored --- a warning is issued when + they're used. + +- [Removed Java Options]\: Removed --- using them results in an error. + +## Standard Options for Java + +These are the most commonly used options supported by all implementations of +the JVM. + +> **Note:** To specify an argument for a long option, you can use either +`--`*name*`=`*value* or `--`*name* *value*. + +`-agentlib:`*libname*\[`=`*options*\] +: Loads the specified native agent library. After the library name, a + comma-separated list of options specific to the library can be used. + If the option `-agentlib:foo` is specified, then the JVM attempts to + load the library named `foo` using the platform specific naming + conventions and locations: + + - **Linux and other POSIX-like platforms:** The JVM attempts to load + the library named `libfoo.so` in the location specified by the + `LD_LIBRARY_PATH` system variable. + + - **macOS:** The JVM attempts to load the library named `libfoo.dylib` + in the location specified by the `DYLD_LIBRARY_PATH` system variable. + + - **Windows:** The JVM attempts to load the library named `foo.dll` in + the location specified by the `PATH` system variable. + + The following example shows how to load the Java Debug Wire Protocol + (JDWP) library and listen for the socket connection on port 8000, + suspending the JVM before the main class loads: + + > `-agentlib:jdwp=transport=dt_socket,server=y,address=8000` + +`-agentpath:`*pathname*\[`=`*options*\] +: Loads the native agent library specified by the absolute path name. This + option is equivalent to `-agentlib` but uses the full path and file name of + the library. + +`--class-path` *classpath*, `-classpath` *classpath*, or `-cp` *classpath* +: Specifies a list of directories, JAR files, and ZIP archives to search + for class files. + + On Windows, semicolons (`;`) separate entities in this list; + on other platforms it is a colon (`:`). + + Specifying *classpath* overrides any setting of the `CLASSPATH` environment + variable. If the class path option isn't used and *classpath* isn't set, + then the user class path consists of the current directory (.). + + As a special convenience, a class path element that contains a base name of + an asterisk (\*) is considered equivalent to specifying a list of all the + files in the directory with the extension `.jar` or `.JAR` . A Java program + can't tell the difference between the two invocations. For example, if the + directory mydir contains `a.jar` and `b.JAR`, then the class path element + mydir/\* is expanded to `A.jar:b.JAR`, except that the order of JAR files + is unspecified. All `.jar` files in the specified directory, even hidden + ones, are included in the list. A class path entry consisting of an + asterisk (\*) expands to a list of all the jar files in the current + directory. The `CLASSPATH` environment variable, where defined, is + similarly expanded. Any class path wildcard expansion that occurs before + the Java VM is started. Java programs never see wildcards that aren't + expanded except by querying the environment, such as by calling + `System.getenv("CLASSPATH")`. + +`--disable-@files` +: Can be used anywhere on the command line, including in an argument file, to + prevent further `@filename` expansion. This option stops expanding + `@`-argfiles after the option. + +`--enable-preview` +: Allows classes to depend on [preview features](https://docs.oracle.com/en/java/javase/12/language/index.html#JSLAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823) of the release. + +`--enable-native-access` *module*\[`,`*module*...\] +: Native access involves access to code or data outside the Java runtime. + This is generally unsafe and, if done incorrectly, might crash the JVM or result + in memory corruption. Native access can occur as a result of calling a method that + is either [restricted](https://openjdk.org/jeps/454#Safety), or `native`. + This option allows code in the specified modules to perform native access. + Native access occurring in a module that has not been explicitly enabled + is deemed *illegal*. + + *module* can be a module name, or `ALL-UNNAMED` to indicate code on the class path. + + +-`--illegal-native-access=`*parameter* +: This option specifies a mode for how illegal native access is handled: + + > **Note:** This option will be removed in a future release. + + - `allow`: This mode allows illegal native access in all modules, + without any warings. + + - `warn`: This mode is identical to `allow` except that a warning + message is issued for the first illegal native access found in a module. + This mode is the default for the current JDK but will change in a future + release. + + - `deny`: This mode disables illegal native access. That is, any illegal native + access causes an `IllegalCallerException`. This mode will become the default + in a future release. + + To verify that your application is ready for a future version of the JDK, + run it with `--illegal-native-access=deny` along with any necessary `--enable-native-access` + options. + +`--finalization=`*value* +: Controls whether the JVM performs finalization of objects. Valid values + are "enabled" and "disabled". Finalization is enabled by default, so the + value "enabled" does nothing. The value "disabled" disables finalization, + so that no finalizers are invoked. + +`--module-path` *modulepath*... or `-p` *modulepath* +: Specifies where to find application modules with a list of path elements. + The elements of a module path can be a file path to a module or a directory + containing modules. Each module is either a modular JAR or an + exploded-module directory. + + On Windows, semicolons (`;`) separate path elements in this list; + on other platforms it is a colon (`:`). + +`--upgrade-module-path` *modulepath*... +: Specifies where to find module replacements of upgradeable modules in the + runtime image with a list of path elements. + The elements of a module path can be a file path to a module or a directory + containing modules. Each module is either a modular JAR or an + exploded-module directory. + + On Windows, semicolons (`;`) separate path elements in this list; + on other platforms it is a colon (`:`). + +`--add-modules` *module*\[`,`*module*...\] +: Specifies the root modules to resolve in addition to the initial module. + *module* can also be `ALL-DEFAULT`, `ALL-SYSTEM`, and `ALL-MODULE-PATH`. + +`--list-modules` +: Lists the observable modules and then exits. + +`-d` *module\_name* or `--describe-module` *module\_name* +: Describes a specified module and then exits. + +`--dry-run` +: Creates the VM but doesn't execute the main method. This `--dry-run` option + might be useful for validating the command-line options such as the module + system configuration. + +`--validate-modules` +: Validates all modules and exit. This option is helpful for finding + conflicts and other errors with modules on the module path. + +`-D`*property*`=`*value* +: Sets a system property value. The *property* variable is a string with no + spaces that represents the name of the property. The *value* variable is a + string that represents the value of the property. If *value* is a string + with spaces, then enclose it in quotation marks (for example + `-Dfoo="foo bar"`). + +`-disableassertions`\[`:`\[*packagename*\]...\|`:`*classname*\] or `-da`\[`:`\[*packagename*\]...\|`:`*classname*\] +: Disables assertions. By default, assertions are disabled in all packages + and classes. With no arguments, `-disableassertions` (`-da`) disables + assertions in all packages and classes. With the *packagename* argument + ending in `...`, the switch disables assertions in the specified package + and any subpackages. If the argument is simply `...`, then the switch + disables assertions in the unnamed package in the current working + directory. With the *classname* argument, the switch disables assertions in + the specified class. + + The `-disableassertions` (`-da`) option applies to all class loaders and to + system classes (which don't have a class loader). There's one exception to + this rule: If the option is provided with no arguments, then it doesn't + apply to system classes. This makes it easy to disable assertions in all + classes except for system classes. The `-disablesystemassertions` option + enables you to disable assertions in all system classes. To explicitly + enable assertions in specific packages or classes, use the + `-enableassertions` (`-ea`) option. Both options can be used at the same + time. For example, to run the `MyClass` application with assertions enabled + in the package `com.wombat.fruitbat` (and any subpackages) but disabled in + the class `com.wombat.fruitbat.Brickbat`, use the following command: + + > `java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat + MyClass` + +`-disablesystemassertions` or `-dsa` +: Disables assertions in all system classes. + +`-enableassertions`\[`:`\[*packagename*\]...\|`:`*classname*\] or `-ea`\[`:`\[*packagename*\]...\|`:`*classname*\] +: Enables assertions. By default, assertions are disabled in all packages and + classes. With no arguments, `-enableassertions` (`-ea`) enables assertions + in all packages and classes. With the *packagename* argument ending in + `...`, the switch enables assertions in the specified package and any + subpackages. If the argument is simply `...`, then the switch enables + assertions in the unnamed package in the current working directory. With + the *classname* argument, the switch enables assertions in the specified + class. + + The `-enableassertions` (`-ea`) option applies to all class loaders and to + system classes (which don't have a class loader). There's one exception to + this rule: If the option is provided with no arguments, then it doesn't + apply to system classes. This makes it easy to enable assertions in all + classes except for system classes. The `-enablesystemassertions` option + provides a separate switch to enable assertions in all system classes. To + explicitly disable assertions in specific packages or classes, use the + `-disableassertions` (`-da`) option. If a single command contains multiple + instances of these switches, then they're processed in order, before + loading any classes. For example, to run the `MyClass` application with + assertions enabled only in the package `com.wombat.fruitbat` (and any + subpackages) but disabled in the class `com.wombat.fruitbat.Brickbat`, use + the following command: + + > `java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat + MyClass` + +`-enablesystemassertions` or `-esa` +: Enables assertions in all system classes. + +`-help`, `-h`, or `-?` +: Prints the help message to the error stream. + +`--help` +: Prints the help message to the output stream. + +`-javaagent:`*jarpath*\[`=`*options*\] +: Loads the specified Java programming language agent. See `java.lang.instrument`. + +`--show-version` +: Prints the product version to the output stream and continues. + +`-showversion` +: Prints the product version to the error stream and continues. + +`--show-module-resolution` +: Shows module resolution output during startup. + +`-splash:`*imagepath* +: Shows the splash screen with the image specified by *imagepath*. HiDPI + scaled images are automatically supported and used if available. The + unscaled image file name, such as `image.ext`, should always be passed as + the argument to the `-splash` option. The most appropriate scaled image + provided is picked up automatically. + + For example, to show the `splash.gif` file from the `images` directory when + starting your application, use the following option: + + > `-splash:images/splash.gif` + + See the SplashScreen API documentation for more information. + +`-verbose:class` +: Displays information about each loaded class. + +`-verbose:gc` +: Displays information about each garbage collection (GC) event. + +`-verbose:jni` +: Displays information about the use of native methods and other Java Native + Interface (JNI) activity. + +`-verbose:module` +: Displays information about the modules in use. + +`--version` +: Prints product version to the output stream and exits. + +`-version` +: Prints product version to the error stream and exits. + +`-X` +: Prints the help on extra options to the error stream. + +`--help-extra` +: Prints the help on extra options to the output stream. + +`@`*argfile* +: Specifies one or more argument files prefixed by `@` used by the `java` + command. It isn't uncommon for the `java` command line to be very long + because of the `.jar` files needed in the classpath. The `@`*argfile* + option overcomes command-line length limitations by enabling the launcher + to expand the contents of argument files after shell expansion, but before + argument processing. Contents in the argument files are expanded because + otherwise, they would be specified on the command line until the + `--disable-@files` option was encountered. + + The argument files can also contain the main class name and all options. If + an argument file contains all of the options required by the `java` + command, then the command line could simply be: + + > `java @`*argfile* + + See [java Command-Line Argument Files] for a description and examples of + using `@`-argfiles. + +## Extra Options for Java + +The following `java` options are general purpose options that are specific to +the Java HotSpot Virtual Machine. + +`-Xbatch` +: Disables background compilation. By default, the JVM compiles the method as + a background task, running the method in interpreter mode until the + background compilation is finished. The `-Xbatch` flag disables background + compilation so that compilation of all methods proceeds as a foreground + task until completed. This option is equivalent to + `-XX:-BackgroundCompilation`. + +`-Xbootclasspath/a:`*directories*\|*zip*\|*JAR-files* +: Specifies a list of directories, JAR files, and ZIP archives to append to + the end of the default bootstrap class path. + + On Windows, semicolons (`;`) separate entities in this list; + on other platforms it is a colon (`:`). + +`-Xcheck:jni` +: Performs additional checks for Java Native Interface (JNI) functions. + + The following checks are considered indicative of significant problems + with the native code, and the JVM terminates with an irrecoverable + error in such cases: + + - The thread doing the call is not attached to the JVM. + - The thread doing the call is using the `JNIEnv` belonging to another + thread. + - A parameter validation check fails: + - A `jfieldID`, or `jmethodID`, is detected as being invalid. For example: + - Of the wrong type + - Associated with the wrong class + - A parameter of the wrong type is detected. + - An invalid parameter value is detected. For example: + - NULL where not permitted + - An out-of-bounds array index, or frame capacity + - A non-UTF-8 string + - An invalid JNI reference + - An attempt to use a `ReleaseXXX` function on a parameter not + produced by the corresponding `GetXXX` function + + The following checks only result in warnings being printed: + + - A JNI call was made without checking for a pending exception from a + previous JNI call, and the current call is not safe when an exception + may be pending. + - A class descriptor is in decorated format (`Lname;`) when it should not be. + - A `NULL` parameter is allowed, but its use is questionable. + - Calling other JNI functions in the scope of `Get/ReleasePrimitiveArrayCritical` + or `Get/ReleaseStringCritical` + + Expect a performance degradation when this option is used. + +`-Xcomp` +: Testing mode to exercise JIT compilers. This option should not be used in production environments. + +`-Xdebug` +: Does nothing; deprecated for removal in a future release. + +`-Xdiag` +: Shows additional diagnostic messages. + +`-Xint` +: Runs the application in interpreted-only mode. Compilation to native code + is disabled, and all bytecode is executed by the interpreter. The + performance benefits offered by the just-in-time (JIT) compiler aren't + present in this mode. + +`-Xinternalversion` +: Displays more detailed JVM version information than the `-version` option, + and then exits. + +`-Xlog:`*option* +: Configure or enable logging with the Java Virtual Machine (JVM) unified + logging framework. See [Enable Logging with the JVM Unified Logging + Framework]. + +`-Xmixed` +: Executes all bytecode by the interpreter except for hot methods, which are + compiled to native code. On by default. Use `-Xint` to switch off. + +`-Xmn` *size* +: Sets the initial and maximum size (in bytes) of the heap for the young + generation (nursery) in the generational collectors. Append the letter + `k` or `K` to indicate kilobytes, `m` or `M` to indicate megabytes, or + `g` or `G` to indicate gigabytes. The young generation region of the heap + is used for new objects. GC is performed in this region more often than + in other regions. If the size for the young generation is too small, then + a lot of minor garbage collections are performed. If the size is too large, + then only full garbage collections are performed, which can take a long + time to complete. It is recommended that you do not set the size for the + young generation for the G1 collector, and keep the size for the young + generation greater than 25% and less than 50% of the overall heap size for + other collectors. + The following examples show how to set the initial and maximum size of + young generation to 256 MB using various units: + + ``` + -Xmn256m + -Xmn262144k + -Xmn268435456 + ``` + + Instead of the `-Xmn` option to set both the initial and maximum size of + the heap for the young generation, you can use `-XX:NewSize` to set the + initial size and `-XX:MaxNewSize` to set the maximum size. + +`-Xms` *size* +: Sets the minimum and the initial size (in bytes) of the heap. This value + must be a multiple of 1024 and greater than 1 MB. Append the letter `k` or + `K` to indicate kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` + to indicate gigabytes. The following examples show how to set the size of + allocated memory to 6 MB using various units: + + ``` + -Xms6291456 + -Xms6144k + -Xms6m + ``` + + If you do not set this option, then the initial size will be set as the sum + of the sizes allocated for the old generation and the young generation. The + initial size of the heap for the young generation can be set using the + `-Xmn` option or the `-XX:NewSize` option. + + Note that the `-XX:InitialHeapSize` option can also be used to set the + initial heap size. If it appears after `-Xms` on the command line, then the + initial heap size gets set to the value specified with `-XX:InitialHeapSize`. + +`-Xmx` *size* +: Specifies the maximum size (in bytes) of the heap. This value + must be a multiple of 1024 and greater than 2 MB. Append the letter `k` or + `K` to indicate kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` + to indicate gigabytes. The default value is chosen at runtime based on system + configuration. For server deployments, `-Xms` and `-Xmx` are often set to + the same value. The following examples show how to set the maximum allowed + size of allocated memory to 80 MB using various units: + + ``` + -Xmx83886080 + -Xmx81920k + -Xmx80m + ``` + + The `-Xmx` option is equivalent to `-XX:MaxHeapSize`. + +`-Xnoclassgc` +: Disables garbage collection (GC) of classes. This can save some GC time, + which shortens interruptions during the application run. When you specify + `-Xnoclassgc` at startup, the class objects in the application are left + untouched during GC and are always be considered live. This can result in + more memory being permanently occupied which, if not used carefully, throws + an out-of-memory exception. + +`-Xrs` +: Reduces the use of operating system signals by the JVM. Shutdown hooks + enable the orderly shutdown of a Java application by running user cleanup + code (such as closing database connections) at shutdown, even if the JVM + terminates abruptly. + + - **Non-Windows:** + + - The JVM catches signals to implement shutdown hooks for unexpected + termination. The JVM uses `SIGHUP`, `SIGINT`, and `SIGTERM` to + initiate the running of shutdown hooks. + + - Applications embedding the JVM frequently need to trap signals such + as `SIGINT` or `SIGTERM`, which can lead to interference with the + JVM signal handlers. The `-Xrs` option is available to address this + issue. When `-Xrs` is used, the signal masks for `SIGINT`, + `SIGTERM`, `SIGHUP`, and `SIGQUIT` aren't changed by the JVM, and + signal handlers for these signals aren't installed. + + - **Windows:** + + - The JVM watches for console control events to implement shutdown + hooks for unexpected termination. Specifically, the JVM registers a + console control handler that begins shutdown-hook processing and + returns `TRUE` for `CTRL_C_EVENT`, `CTRL_CLOSE_EVENT`, + `CTRL_LOGOFF_EVENT`, and `CTRL_SHUTDOWN_EVENT`. + + - The JVM uses a similar mechanism to implement the feature of + dumping thread stacks for debugging purposes. The JVM uses + `CTRL_BREAK_EVENT` to perform thread dumps. + + - If the JVM is run as a service (for example, as a servlet engine + for a web server), then it can receive `CTRL_LOGOFF_EVENT` but + shouldn't initiate shutdown because the operating system doesn't + actually terminate the process. To avoid possible interference such + as this, the `-Xrs` option can be used. When the `-Xrs` option is + used, the JVM doesn't install a console control handler, implying + that it doesn't watch for or process `CTRL_C_EVENT`, + `CTRL_CLOSE_EVENT`, `CTRL_LOGOFF_EVENT`, or `CTRL_SHUTDOWN_EVENT`. + + There are two consequences of specifying `-Xrs`: + + - **Non-Windows:** `SIGQUIT` thread dumps aren't + available. + + - **Windows:** Ctrl + Break thread dumps aren't available. + + User code is responsible for causing shutdown hooks to run, for example, by + calling `System.exit()` when the JVM is to be terminated. + +`-Xshare:`*mode* +: Sets the class data sharing (CDS) mode. + + Possible *mode* arguments for this option include the following: + + `auto` + : Use shared class data if possible (default). + + `on` + : Require using shared class data, otherwise fail. + + > **Note:** The `-Xshare:on` option is used for testing purposes only. + It may cause the VM to unexpectedly exit during start-up when the CDS + archive cannot be used (for example, when certain VM parameters are changed, + or when a different JDK is used). This option should not be used + in production environments. + + `off` + : Do not attempt to use shared class data. + +`-XshowSettings` +: Shows all settings and then continues. + +`-XshowSettings:`*category* +: Shows settings and continues. Possible *category* arguments for this option + include the following: + + `all` + : Shows all categories of settings in **verbose** detail. + + `locale` + : Shows settings related to locale. + + `properties` + : Shows settings related to system properties. + + `security` + : Shows all settings related to security. + + sub-category arguments for `security` include the following: + + * `security:all` : shows all security settings + * `security:properties` : shows security properties + * `security:providers` : shows static security provider settings + * `security:tls` : shows TLS related security settings + + `vm` + : Shows the settings of the JVM. + + `system` + : **Linux only:** Shows host system or container configuration and continues. + +`-Xss` *size* +: Sets the thread stack size (in bytes). Append the letter `k` or `K` to + indicate KB, `m` or `M` to indicate MB, or `g` or `G` to indicate GB. The + actual size may be rounded up to a multiple of the system page size as + required by the operating system. The default value depends on the + platform. For example: + + - Linux/x64: 1024 KB + + - Linux/Aarch64: 2048 KB + + - macOS/x64: 1024 KB + + - macOS/Aarch64: 2048 KB + + - Windows: The default value depends on virtual memory + + The following examples set the thread stack size to 1024 KB in different + units: + + ``` + -Xss1m + -Xss1024k + -Xss1048576 + ``` + + This option is similar to `-XX:ThreadStackSize`. + +`--add-reads` *module*`=`*target-module*(`,`*target-module*)\* +: Updates *module* to read the *target-module*, regardless of the module + declaration. *target-module* can be `ALL-UNNAMED` to read all unnamed + modules. + +`--add-exports` *module*`/`*package*`=`*target-module*(`,`*target-module*)\* +: Updates *module* to export *package* to *target-module*, regardless of + module declaration. *target-module* can be `ALL-UNNAMED` to export to all + unnamed modules. + +`--add-opens` *module*`/`*package*`=`*target-module*(`,`*target-module*)\* +: Updates *module* to open *package* to *target-module*, regardless of module + declaration. + +`--limit-modules` *module*\[`,`*module*...\] +: Specifies the limit of the universe of observable modules. + +`--patch-module` *module*`=`*file*(`;`*file*)\* +: Overrides or augments a module with classes and resources in JAR files or + directories. + +`--source` *version* +: Sets the version of the source in source-file mode. + + +`--sun-misc-unsafe-memory-access=` *value* +: Allow or deny usage of unsupported API `sun.misc.Unsafe`. *value* is one of: + + `allow` + : Allow use of the memory-access methods with no warnings at run time. + + `warn` + : Allow use of the memory-access methods, but issues a warning on the first + occasion that any memory-access method is used. At most one warning is + issued. + + `debug` + : Allow use of the memory-access methods, but issue a one-line warning and + a stack trace when any memory-access method is used. + + `deny` + : Disallow use of the memory-access methods by throwing an + `UnsupportedOperationException` on every usage. + + The default value when the option is not specified is `allow`. + + +## Extra Options for macOS + +The following extra options are macOS specific. + +`-XstartOnFirstThread` +: Runs the `main()` method on the first (AppKit) thread. + +`-Xdock:name=`*application\_name* +: Overrides the default application name displayed in dock. + +`-Xdock:icon=`*path\_to\_icon\_file* +: Overrides the default icon displayed in dock. + +## Advanced Options for Java + +These `java` options can be used to enable other advanced options. + +`-XX:+UnlockDiagnosticVMOptions` +: Unlocks the options intended for diagnosing the JVM. By default, this + option is disabled and diagnostic options aren't available. + + Command line options that are enabled with the use of this option are + not supported. If you encounter issues while using any of these + options, it is very likely that you will be required to reproduce the + problem without using any of these unsupported options before Oracle + Support can assist with an investigation. It is also possible that any + of these options may be removed or their behavior changed without any + warning. + +`-XX:+UnlockExperimentalVMOptions` +: Unlocks the options that provide experimental features in the JVM. + By default, this option is disabled and experimental features aren't available. + +## Advanced Runtime Options for Java + +These `java` options control the runtime behavior of the Java HotSpot VM. + +`-XX:ActiveProcessorCount=`*x* +: Overrides the number of CPUs that the VM will use to calculate the size of + thread pools it will use for various operations such as Garbage Collection + and ForkJoinPool. + + The VM normally determines the number of available processors from the + operating system. This flag can be useful for partitioning CPU resources + when running multiple Java processes in docker containers. This flag is + honored even if `UseContainerSupport` is not enabled. See + `-XX:-UseContainerSupport` for a description of enabling and disabling + container support. + +`-XX:AllocateHeapAt=`*path* +: Takes a path to the file system and uses memory mapping to allocate the + object heap on the memory device. Using this option enables the HotSpot VM + to allocate the Java object heap on an alternative memory device, such as + an NV-DIMM, specified by the user. + + Alternative memory devices that have the same semantics as DRAM, including + the semantics of atomic operations, can be used instead of DRAM for the + object heap without changing the existing application code. All other + memory structures (such as the code heap, metaspace, and thread stacks) + continue to reside in DRAM. + + Some operating systems expose non-DRAM memory through the file system. + Memory-mapped files in these file systems bypass the page cache and provide + a direct mapping of virtual memory to the physical memory on the device. + The existing heap related flags (such as `-Xmx` and `-Xms`) and + garbage-collection related flags continue to work as before. + +`-XX:-CompactStrings` +: Disables the Compact Strings feature. By default, this option is enabled. + When this option is enabled, Java Strings containing only single-byte + characters are internally represented and stored as + single-byte-per-character Strings using ISO-8859-1 / Latin-1 encoding. This + reduces, by 50%, the amount of space required for Strings containing only + single-byte characters. For Java Strings containing at least one multibyte + character: these are represented and stored as 2 bytes per character using + UTF-16 encoding. Disabling the Compact Strings feature forces the use of + UTF-16 encoding as the internal representation for all Java Strings. + + Cases where it may be beneficial to disable Compact Strings include the + following: + + - When it's known that an application overwhelmingly will be allocating + multibyte character Strings + + - In the unexpected event where a performance regression is observed in + migrating from Java SE 8 to Java SE 9 and an analysis shows that + Compact Strings introduces the regression + + In both of these scenarios, disabling Compact Strings makes sense. + +`-XX:ErrorFile=`*filename* +: Specifies the path and file name to which error data is written when an + irrecoverable error occurs. By default, this file is created in the current + working directory and named `hs_err_pid`*pid*`.log` where *pid* is the + identifier of the process that encountered the error. + + The following example shows how to set the default log file (note that the + identifier of the process is specified as `%p`): + + > `-XX:ErrorFile=./hs_err_pid%p.log` + + - **Non-Windows:** The following example shows how to + set the error log to `/var/log/java/java_error.log`: + + > `-XX:ErrorFile=/var/log/java/java_error.log` + + - **Windows:** The following example shows how to set the error log file + to `C:/log/java/java_error.log`: + + > `-XX:ErrorFile=C:/log/java/java_error.log` + + If the file exists, and is writeable, then it will be overwritten. + Otherwise, if the file can't be created in the specified directory (due to + insufficient space, permission problem, or another issue), then the file is + created in the temporary directory for the operating system: + + - **Non-Windows:** The temporary directory is `/tmp`. + + - **Windows:** The temporary directory is specified by the value of the + `TMP` environment variable; if that environment variable isn't defined, + then the value of the `TEMP` environment variable is used. + +`-XX:+ExtensiveErrorReports` +: Enables the reporting of more extensive error information in the `ErrorFile`. + This option can be turned on in environments where maximal information is + desired - even if the resulting logs may be quite large and/or contain + information that might be considered sensitive. The information can vary + from release to release, and across different platforms. By default this + option is disabled. + +`-XX:FlightRecorderOptions=`*parameter*`=`*value* (or) `-XX:FlightRecorderOptions:`*parameter*`=`*value* +: Sets the parameters that control the behavior of JFR. Multiple parameters can be specified + by separating them with a comma. + + The following list contains the available JFR *parameter*`=`*value* + entries: + + `globalbuffersize=`*size* + : Specifies the total amount of primary memory used for data retention. + The default value is based on the value specified for `memorysize`. + Change the `memorysize` parameter to alter the size of global buffers. + + `maxchunksize=`*size* + : Specifies the maximum size (in bytes) of the data chunks in a + recording. Append `m` or `M` to specify the size in megabytes (MB), or + `g` or `G` to specify the size in gigabytes (GB). By default, the + maximum size of data chunks is set to 12 MB. The minimum allowed is 1 + MB. + + `memorysize=`*size* + : Determines how much buffer memory should be used, and sets the + `globalbuffersize` and `numglobalbuffers` parameters based on the size + specified. Append `m` or `M` to specify the size in megabytes (MB), or + `g` or `G` to specify the size in gigabytes (GB). By default, the + memory size is set to 10 MB. + + `numglobalbuffers` + : Specifies the number of global buffers used. The default value is based + on the memory size specified. Change the `memorysize` parameter to + alter the number of global buffers. + + `old-object-queue-size=number-of-objects` + : Maximum number of old objects to track. By default, the number of + objects is set to 256. + + `preserve-repository=`{`true`\|`false`} + : Specifies whether files stored in the disk repository should be kept + after the JVM has exited. If false, files are deleted. By default, + this parameter is disabled. + + `repository=`*path* + : Specifies the repository (a directory) for temporary disk storage. By + default, the system's temporary directory is used. + + `retransform=`{`true`\|`false`} + : Specifies whether event classes should be retransformed using JVMTI. If + false, instrumentation is added when event classes are loaded. By + default, this parameter is enabled. + + `stackdepth=`*depth* + : Stack depth for stack traces. By default, the depth is set to 64 method + calls. The maximum is 2048. Values greater than 64 could create + significant overhead and reduce performance. + + `threadbuffersize=`*size* + : Specifies the per-thread local buffer size (in bytes). By default, the + local buffer size is set to 8 kilobytes, with a minimum value of + 4 kilobytes. Overriding this parameter + could reduce performance and is not recommended. + +`-XX:LargePageSizeInBytes=`*size* +: Sets the maximum large page size (in bytes) used by the JVM. The + *size* argument must be a valid page size supported by the environment + to have any effect. Append the letter `k` or `K` to indicate kilobytes, + `m` or `M` to indicate megabytes, or `g` or `G` to indicate gigabytes. + By default, the size is set to 0, meaning that the JVM will use the + default large page size for the environment as the maximum size for + large pages. See [Large Pages]. + + The following example describes how to set the large page size to 1 + gigabyte (GB): + + > `-XX:LargePageSizeInBytes=1g` + +`-XX:MaxDirectMemorySize=`*size* +: Sets the maximum total size (in bytes) of the `java.nio` package, + direct-buffer allocations. Append the letter `k` or `K` to indicate + kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` to indicate + gigabytes. If not set, the flag is ignored and the JVM chooses the size + for NIO direct-buffer allocations automatically. + + The following examples illustrate how to set the NIO size to 1024 KB in + different units: + + ``` + -XX:MaxDirectMemorySize=1m + -XX:MaxDirectMemorySize=1024k + -XX:MaxDirectMemorySize=1048576 + ``` + +`-XX:-MaxFDLimit` +: Disables the attempt to set the soft limit for the number of open file + descriptors to the hard limit. By default, this option is enabled on all + platforms, but is ignored on Windows. The only time that you may need to + disable this is on macOS, where its use imposes a maximum of 10240, which + is lower than the actual system maximum. + +`-XX:NativeMemoryTracking=`*mode* +: Specifies the mode for tracking JVM native memory usage. Possible *mode* + arguments for this option include the following: + + `off` + : Instructs not to track JVM native memory usage. This is the default + behavior if you don't specify the `-XX:NativeMemoryTracking` option. + + `summary` + : Tracks memory usage only by JVM subsystems, such as Java heap, class, + code, and thread. + + `detail` + : In addition to tracking memory usage by JVM subsystems, track memory + usage by individual `CallSite`, individual virtual memory region and + its committed regions. + +`-XX:TrimNativeHeapInterval=`*millis* +: Interval, in ms, at which the JVM will trim the native heap. Lower values + will reclaim memory more eagerly at the cost of higher overhead. A value + of 0 (default) disables native heap trimming. + Native heap trimming is performed in a dedicated thread. + + This option is only supported on Linux with GNU C Library (glibc). + +`-XX:+NeverActAsServerClassMachine` +: Enable the "Client VM emulation" mode which only uses the C1 JIT compiler, + a 32Mb CodeCache and the Serial GC. The maximum amount of memory that the + JVM may use (controlled by the `-XX:MaxRAM=n` flag) is set to 1GB by default. + The string "emulated-client" is added to the JVM version string. + + By default the flag is set to `true` only on Windows in 32-bit mode and + `false` in all other cases. + + The "Client VM emulation" mode will not be enabled if any of the following + flags are used on the command line: + + ``` + -XX:{+|-}TieredCompilation + -XX:CompilationMode=mode + -XX:TieredStopAtLevel=n + -XX:{+|-}EnableJVMCI + -XX:{+|-}UseJVMCICompiler + ``` + +`-XX:ObjectAlignmentInBytes=`*alignment* +: Sets the memory alignment of Java objects (in bytes). By default, the value + is set to 8 bytes. The specified value should be a power of 2, and must be + within the range of 8 and 256 (inclusive). This option makes it possible to + use compressed pointers with large Java heap sizes. + + The heap size limit in bytes is calculated as: + + > `4GB * ObjectAlignmentInBytes` + + > **Note:** As the alignment value increases, the unused space between objects also + increases. As a result, you may not realize any benefits from using + compressed pointers with large Java heap sizes. + +`-XX:OnError=`*string* +: Sets a custom command or a series of semicolon-separated commands to run + when an irrecoverable error occurs. If the string contains spaces, then it + must be enclosed in quotation marks. + + - **Non-Windows:** The following example shows how + the `-XX:OnError` option can be used to run the `gcore` command to + create a core image, and start the `gdb` debugger to attach to the + process in case of an irrecoverable error (the `%p` designates the + current process identifier): + + > `-XX:OnError="gcore %p;gdb -p %p"` + + - **Windows:** The following example shows how the `-XX:OnError` option + can be used to run the `userdump.exe` utility to obtain a crash dump in + case of an irrecoverable error (the `%p` designates the current + process identifier). This example assumes that the path to the `userdump.exe` + utility is specified in the `PATH` environment variable: + + > `-XX:OnError="userdump.exe %p"` + +`-XX:OnOutOfMemoryError=`*string* +: Sets a custom command or a series of semicolon-separated commands to run + when an `OutOfMemoryError` exception is first thrown. If the string + contains spaces, then it must be enclosed in quotation marks. For an + example of a command string, see the description of the `-XX:OnError` + option. + +`-XX:+PrintCommandLineFlags` +: Enables printing of ergonomically selected JVM flags that appeared on the + command line. It can be useful to know the ergonomic values set by the JVM, + such as the heap space size and the selected garbage collector. By default, + this option is disabled and flags aren't printed. + +`-XX:+PreserveFramePointer` +: Selects between using the RBP register as a general purpose register + (`-XX:-PreserveFramePointer`) and using the RBP register to hold the frame + pointer of the currently executing method (`-XX:+PreserveFramePointer` . If + the frame pointer is available, then external profiling tools (for example, + Linux perf) can construct more accurate stack traces. + +`-XX:+PrintNMTStatistics` +: Enables printing of collected native memory tracking data at JVM exit when + native memory tracking is enabled (see `-XX:NativeMemoryTracking`). By + default, this option is disabled and native memory tracking data isn't + printed. + +`-XX:SharedArchiveFile=`*path* +: Specifies the path and name of the class data sharing (CDS) archive file + + See [Application Class Data Sharing]. + +`-XX:+VerifySharedSpaces` +: If this option is specified, the JVM will load a CDS archive file only if it + passes an integrity check based on CRC32 checksums. The purpose of this flag is + to check for unintentional damage to CDS archive files in transmission or storage. + To guarantee the security and proper operation of CDS, the user must + ensure that the CDS archive files used by Java applications cannot be modified without + proper authorization. + +`-XX:SharedArchiveConfigFile=`*shared\_config\_file* +: Specifies additional shared data added to the archive file. + +`-XX:SharedClassListFile=`*file\_name* +: Specifies the text file that contains the names of the classes to store in + the class data sharing (CDS) archive. This file contains the full name of + one class per line, except slashes (`/`) replace dots (`.`). For example, + to specify the classes `java.lang.Object` and `hello.Main`, create a text + file that contains the following two lines: + + ``` + java/lang/Object + hello/Main + ``` + + The classes that you specify in this text file should include the classes + that are commonly used by the application. They may include any classes + from the application, extension, or bootstrap class paths. + + See [Application Class Data Sharing]. + +`-XX:+ShowCodeDetailsInExceptionMessages` +: Enables printing of improved `NullPointerException` messages. When an application throws a + `NullPointerException`, the option enables the JVM to analyze the program's bytecode + instructions to determine precisely which reference is `null`, + and describes the source with a null-detail message. + The null-detail message is calculated and returned by `NullPointerException.getMessage()`, + and will be printed as the exception message along with + the method, filename, and line number. By default, this option is enabled. + +`-XX:+ShowMessageBoxOnError` +: Enables the display of a dialog box when the JVM experiences an + irrecoverable error. This prevents the JVM from exiting and keeps the + process active so that you can attach a debugger to it to investigate the + cause of the error. By default, this option is disabled. + +`-XX:StartFlightRecording:`*parameter*`=`*value* +: Starts a JFR recording for the Java application. This option is equivalent + to the `JFR.start` diagnostic command that starts a recording during + runtime. `-XX:StartFlightRecording:help` prints available options and + example command lines. You can set the following *parameter*`=`*value* + entries when starting a JFR recording: + + `delay=`*time* + : Specifies the delay between the Java application launch time and the + start of the recording. Append `s` to specify the time in seconds, `m` + for minutes, `h` for hours, or `d` for days (for example, specifying + `10m` means 10 minutes). By default, there's no delay, and this + parameter is set to 0. + + `disk=`{`true`\|`false`} + : Specifies whether to write data to disk while recording. By default, + this parameter is enabled. + + `dumponexit=`{`true`\|`false`} + : Specifies if the running recording is dumped when the JVM shuts down. + If enabled and a `filename` is not entered, the recording is written to + a file in the directory where the process was started. The file name is + a system-generated name that contains the process ID, recording ID, and + current timestamp, similar to + `hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr`. By default, this + parameter is disabled. + + `duration=`*time* + : Specifies the duration of the recording. Append `s` to specify the time + in seconds, `m` for minutes, `h` for hours, or `d` for days (for + example, specifying `5h` means 5 hours). By default, the duration isn't + limited, and this parameter is set to 0. + + `filename=`*path* + : Specifies the path and name of the file to which the recording is + written when the recording is stopped, for example: + + - `recording.jfr` + - `/home/user/recordings/recording.jfr` + - `c:\recordings\recording.jfr` + + If %p and/or %t is specified in the filename, it expands to the JVM's + PID and the current timestamp, respectively. The filename may also be + a directory in which case, the filename is generated from the PID + and the current date in the specified directory. + + `name=`*identifier* + : Takes both the name and the identifier of a recording. + + `maxage=`*time* + : Specifies the maximum age of disk data to keep for the recording. This + parameter is valid only when the `disk` parameter is set to `true`. + Append `s` to specify the time in seconds, `m` for minutes, `h` for + hours, or `d` for days (for example, specifying `30s` means 30 + seconds). By default, the maximum age isn't limited, and this parameter + is set to `0s`. + + `maxsize=`*size* + : Specifies the maximum size (in bytes) of disk data to keep for the + recording. This parameter is valid only when the `disk` parameter is + set to `true`. The value must not be less than the value for the + `maxchunksize` parameter set with `-XX:FlightRecorderOptions`. Append + `m` or `M` to specify the size in megabytes, or `g` or `G` to specify + the size in gigabytes. By default, the maximum size of disk data isn't + limited, and this parameter is set to `0`. + + `path-to-gc-roots=`{`true`\|`false`} + : Specifies whether to collect the path to garbage collection (GC) roots + at the end of a recording. By default, this parameter is disabled. + + The path to GC roots is useful for finding memory leaks, but collecting + it is time-consuming. Enable this option only when you start a + recording for an application that you suspect has a memory leak. If the + `settings` parameter is set to `profile`, the stack trace from where + the potential leaking object was allocated is included in the + information collected. + + `settings=`*path* + : Specifies the path and name of the event settings file (of type JFC). + By default, the `default.jfc` file is used, which is located in + `JAVA_HOME/lib/jfr`. This default settings file collects a predefined + set of information with low overhead, so it has minimal impact on + performance and can be used with recordings that run continuously. + + A second settings file is also provided, profile.jfc, which provides + more data than the default configuration, but can have more overhead + and impact performance. Use this configuration for short periods of + time when more information is needed. + + You can specify values for multiple parameters by separating them with a + comma. Event settings and .jfc options can be specified using the + following syntax: + + `option=`*value* + : Specifies the option value to modify. To list available options, use + the `JAVA_HOME`/bin/jfr tool. + + `event-setting=`*value* + : Specifies the event setting value to modify. Use the form: + `#=`. + To add a new event setting, prefix the event name with '+'. + + You can specify values for multiple event settings and .jfc options by + separating them with a comma. In case of a conflict between a parameter + and a .jfc option, the parameter will take precedence. The whitespace + delimiter can be omitted for timespan values, i.e. 20ms. For more + information about the settings syntax, see Javadoc of the jdk.jfr + package. + + To only see warnings and errors from JFR during startup set + -Xlog:jfr+startup=warning. + +`-XX:ThreadStackSize=`*size* +: Sets the Java thread stack size (in kilobytes). Use of a scaling suffix, + such as `k`, results in the scaling of the kilobytes value so that + `-XX:ThreadStackSize=1k` sets the Java thread stack size to 1024\*1024 + bytes or 1 megabyte. The default value depends on the platform. For example: + + - Linux/x64: 1024 KB + + - Linux/Aarch64: 2048 KB + + - macOS/x64: 1024 KB + + - macOS/Aarch64: 2048 KB + + - Windows: The default value depends on virtual memory + + The following examples show how to set the thread stack size to 1 megabyte + in different units: + + ``` + -XX:ThreadStackSize=1k + -XX:ThreadStackSize=1024 + ``` + + This option is similar to `-Xss`. + +`-XX:-UseCompressedOops` +: Disables the use of compressed pointers. By default, this option is + enabled, and compressed pointers are used. This will automatically limit + the maximum ergonomically determined Java heap size to the maximum amount + of memory that can be covered by compressed pointers. By default this range + is 32 GB. + + With compressed oops enabled, object references are represented + as 32-bit offsets instead of 64-bit pointers, which typically increases + performance when running the application with Java heap sizes smaller than + the compressed oops pointer range. This option works only for 64-bit JVMs. + + It's possible to use compressed pointers with Java heap sizes greater than + 32 GB. See the `-XX:ObjectAlignmentInBytes` option. + +`-XX:-UseContainerSupport` +: **Linux only:** The VM now provides automatic container detection support, which allows the + VM to determine the amount of memory and number of processors that are + available to a Java process running in docker containers. It uses this + information to allocate system resources. The default for this flag is `true`, + and container support is enabled by default. It can be disabled + with `-XX:-UseContainerSupport`. + + Unified Logging is available to help to diagnose issues related to this + support. + + Use `-Xlog:os+container=trace` for maximum logging of container + information. See [Enable Logging with the JVM Unified Logging Framework] + for a description of using Unified Logging. + +`-XX:+UseLargePages` +: Enables the use of large page memory. By default, this option is disabled + and large page memory isn't used. + + See [Large Pages]. + +`-XX:+UseTransparentHugePages` +: **Linux only:** Enables the use of large pages that can dynamically grow or + shrink. This option is disabled by default. You may encounter performance + problems with transparent huge pages as the OS moves other pages around to + create huge pages; this option is made available for experimentation. + +`-XX:+AllowUserSignalHandlers` +: **Non-Windows:** Enables installation of signal handlers by the application. By default, + this option is disabled and the application isn't allowed to install signal + handlers. + +`-XX:VMOptionsFile=`*filename* +: Allows user to specify VM options in a file, for example, + `java -XX:VMOptionsFile=/var/my_vm_options HelloWorld`. + +`-XX:UseBranchProtection=`*mode* +: **Linux AArch64 only:** Specifies the branch protection mode. + All options other than + `none` require the VM to have been built with branch protection + enabled. In addition, for full protection, any native libraries + provided by applications should be compiled with the same level + of protection. + + Possible *mode* arguments for this option include the following: + + `none` + : Do not use branch protection. This is the default value. + + `standard` + : Enables all branch protection modes available on the current platform. + + `pac-ret` + : Enables protection against ROP based attacks. (AArch64 8.3+ only) + +## Advanced JIT Compiler Options for java + +These `java` options control the dynamic just-in-time (JIT) compilation +performed by the Java HotSpot VM. + +`-XX:AllocateInstancePrefetchLines=`*lines* +: Sets the number of lines to prefetch ahead of the instance allocation + pointer. By default, the number of lines to prefetch is set to 1: + + > `-XX:AllocateInstancePrefetchLines=1` + + +`-XX:AllocatePrefetchDistance=`*size* +: Sets the size (in bytes) of the prefetch distance for object allocation. + Memory about to be written with the value of new objects is prefetched up + to this distance starting from the address of the last allocated object. + Each Java thread has its own allocation point. + + Negative values denote that prefetch distance is chosen based on the + platform. Positive values are bytes to prefetch. Append the letter `k` or + `K` to indicate kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` + to indicate gigabytes. The default value is set to -1. + + The following example shows how to set the prefetch distance to 1024 bytes: + + > `-XX:AllocatePrefetchDistance=1024` + + +`-XX:AllocatePrefetchInstr=`*instruction* +: Sets the prefetch instruction to prefetch ahead of the allocation pointer. + Possible values are from 0 to 3. The actual instructions behind the values + depend on the platform. By default, the prefetch instruction is set to 0: + + > `-XX:AllocatePrefetchInstr=0` + + +`-XX:AllocatePrefetchLines=`*lines* +: Sets the number of cache lines to load after the last object allocation by + using the prefetch instructions generated in compiled code. The default + value is 1 if the last allocated object was an instance, and 3 if it was an + array. + + The following example shows how to set the number of loaded cache lines to + 5: + + > `-XX:AllocatePrefetchLines=5` + + +`-XX:AllocatePrefetchStepSize=`*size* +: Sets the step size (in bytes) for sequential prefetch instructions. Append + the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate + megabytes, `g` or `G` to indicate gigabytes. By default, the step size is + set to 16 bytes: + + > `-XX:AllocatePrefetchStepSize=16` + + +`-XX:AllocatePrefetchStyle=`*style* +: Sets the generated code style for prefetch instructions. The *style* + argument is an integer from 0 to 3: + + `0` + : Don't generate prefetch instructions. + + `1` + : Execute prefetch instructions after each allocation. This is the + default setting. + + `2` + : Use the thread-local allocation block (TLAB) watermark pointer to + determine when prefetch instructions are executed. + + `3` + : Generate one prefetch instruction per cache line. + + +`-XX:+BackgroundCompilation` +: Enables background compilation. This option is enabled by default. To + disable background compilation, specify `-XX:-BackgroundCompilation` (this + is equivalent to specifying `-Xbatch`). + +`-XX:CICompilerCount=`*threads* +: Sets the number of compiler threads to use for compilation. + By default, the number of compiler threads is selected automatically + depending on the number of CPUs and memory available for compiled code. + The following example shows how to set the number of threads to 2: + + > `-XX:CICompilerCount=2` + +`-XX:+UseDynamicNumberOfCompilerThreads` +: Dynamically create compiler thread up to the limit specified by `-XX:CICompilerCount`. + This option is enabled by default. + +`-XX:CompileCommand=`*command*`,`*method*\[`,`*option*\] +: Specifies a *command* to perform on a *method*. For example, to exclude the + `indexOf()` method of the `String` class from being compiled, use the + following: + + > `-XX:CompileCommand=exclude,java/lang/String.indexOf` + + Note that the full class name is specified, including all packages and + subpackages separated by a slash (`/`). For easier cut-and-paste + operations, it's also possible to use the method name format produced by + the `-XX:+PrintCompilation` and `-XX:+LogCompilation` options: + + > `-XX:CompileCommand=exclude,java.lang.String::indexOf` + + If the method is specified without the signature, then the command is + applied to all methods with the specified name. However, you can also + specify the signature of the method in the class file format. In this case, + you should enclose the arguments in quotation marks, because otherwise the + shell treats the semicolon as a command end. For example, if you want to + exclude only the `indexOf(String)` method of the `String` class from being + compiled, use the following: + + > `-XX:CompileCommand="exclude,java/lang/String.indexOf,(Ljava/lang/String;)I"` + + You can also use the asterisk (\*) as a wildcard for class and method + names. For example, to exclude all `indexOf()` methods in all classes from + being compiled, use the following: + + > `-XX:CompileCommand=exclude,*.indexOf` + + The commas and periods are aliases for spaces, making it easier to pass + compiler commands through a shell. You can pass arguments to + `-XX:CompileCommand` using spaces as separators by enclosing the argument + in quotation marks: + + > `-XX:CompileCommand="exclude java/lang/String indexOf"` + + Note that after parsing the commands passed on the command line using the + `-XX:CompileCommand` options, the JIT compiler then reads commands from the + `.hotspot_compiler` file. You can add commands to this file or specify a + different file using the `-XX:CompileCommandFile` option. + + To add several commands, either specify the `-XX:CompileCommand` option + multiple times, or separate each argument with the new line separator + (`\n`). The following commands are available: + + `break` + : Sets a breakpoint when debugging the JVM to stop at the beginning of + compilation of the specified method. + + `compileonly` + : Excludes all methods from compilation except for the specified method. + As an alternative, you can use the `-XX:CompileOnly` option, which lets + you specify several methods. + + `dontinline` + : Prevents inlining of the specified method. + + `exclude` + : Excludes the specified method from compilation. + + `help` + : Prints a help message for the `-XX:CompileCommand` option. + + `inline` + : Attempts to inline the specified method. + + `log` + : Excludes compilation logging (with the `-XX:+LogCompilation` option) + for all methods except for the specified method. By default, logging is + performed for all compiled methods. + + `option` + : Passes a JIT compilation option to the specified method in place of the + last argument (`option`). The compilation option is set at the end, + after the method name. For example, to enable the + `BlockLayoutByFrequency` option for the `append()` method of the + `StringBuffer` class, use the following: + + > `-XX:CompileCommand=option,java/lang/StringBuffer.append,BlockLayoutByFrequency` + + You can specify multiple compilation options, separated by commas or + spaces. + + `print` + : Prints generated assembler code after compilation of the specified + method. + + `quiet` + : Instructs not to print the compile commands. By default, the commands + that you specify with the `-XX:CompileCommand` option are printed; for + example, if you exclude from compilation the `indexOf()` method of the + `String` class, then the following is printed to standard output: + + > `CompilerOracle: exclude java/lang/String.indexOf` + + You can suppress this by specifying the `-XX:CompileCommand=quiet` + option before other `-XX:CompileCommand` options. + +`-XX:CompileCommandFile=`*filename* +: Sets the file from which JIT compiler commands are read. By default, the + `.hotspot_compiler` file is used to store commands performed by the JIT + compiler. + + Each line in the command file represents a command, a class name, and a + method name for which the command is used. For example, this line prints + assembly code for the `toString()` method of the `String` class: + + > `print java/lang/String toString` + + If you're using commands for the JIT compiler to perform on methods, then + see the `-XX:CompileCommand` option. + +`-XX:CompilerDirectivesFile=`*file* +: Adds directives from a file to the directives stack when a program starts. + See [Compiler Control](https://docs.oracle.com/en/java/javase/12/vm/compiler-control1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A). + + The `-XX:CompilerDirectivesFile` option has to be used together with the + `-XX:UnlockDiagnosticVMOptions` option that unlocks diagnostic JVM options. + + +`-XX:+CompilerDirectivesPrint` +: Prints the directives stack when the program starts or when a new directive + is added. + + The `-XX:+CompilerDirectivesPrint` option has to be used together with the + `-XX:UnlockDiagnosticVMOptions` option that unlocks diagnostic JVM options. + +`-XX:CompileOnly=`*methods* +: Sets the list of methods (separated by commas) to which compilation should + be restricted. Only the specified methods are compiled. + + `-XX:CompileOnly=method1,method2,...,methodN` is an alias for: + ``` + -XX:CompileCommand=compileonly,method1 + -XX:CompileCommand=compileonly,method2 + ... + -XX:CompileCommand=compileonly,methodN + ``` + +`-XX:CompileThresholdScaling=`*scale* +: Provides unified control of first compilation. This option controls when + methods are first compiled for both the tiered and the nontiered modes of + operation. The `CompileThresholdScaling` option has a floating point value + between 0 and +Inf and scales the thresholds corresponding to the current + mode of operation (both tiered and nontiered). Setting + `CompileThresholdScaling` to a value less than 1.0 results in earlier + compilation while values greater than 1.0 delay compilation. Setting + `CompileThresholdScaling` to 0 is equivalent to disabling compilation. + +`-XX:+DoEscapeAnalysis` +: Enables the use of escape analysis. This option is enabled by default. To + disable the use of escape analysis, specify `-XX:-DoEscapeAnalysis`. + +`-XX:InitialCodeCacheSize=`*size* +: Sets the initial code cache size (in bytes). Append the letter `k` or `K` + to indicate kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` to + indicate gigabytes. The default value depends on the platform. The initial code + cache size shouldn't be less than the system's minimal memory page size. + The following example shows how to set the initial code cache size to 32 + KB: + + > `-XX:InitialCodeCacheSize=32k` + +`-XX:+Inline` +: Enables method inlining. This option is enabled by default to increase + performance. To disable method inlining, specify `-XX:-Inline`. + +`-XX:InlineSmallCode=`*size* +: Sets the maximum code size (in bytes) for already compiled methods + that may be inlined. This flag only applies to the C2 compiler. + Append the letter `k` or `K` to indicate kilobytes, + `m` or `M` to indicate megabytes, or `g` or `G` to indicate gigabytes. + The default value depends on the platform and on whether tiered compilation + is enabled. In the following example it is set to 1000 bytes: + + > `-XX:InlineSmallCode=1000` + +`-XX:+LogCompilation` +: Enables logging of compilation activity to a file named `hotspot.log` in + the current working directory. You can specify a different log file path + and name using the `-XX:LogFile` option. + + By default, this option is disabled and compilation activity isn't logged. + The `-XX:+LogCompilation` option has to be used together with the + `-XX:UnlockDiagnosticVMOptions` option that unlocks diagnostic JVM options. + + You can enable verbose diagnostic output with a message printed to the + console every time a method is compiled by using the + `-XX:+PrintCompilation` option. + + +`-XX:FreqInlineSize=`*size* +: Sets the maximum bytecode size (in bytes) of a hot method to be inlined. + This flag only applies to the C2 compiler. Append + the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate + megabytes, or `g` or `G` to indicate gigabytes. The default value depends + on the platform. In the following example it is set to 325 bytes: + + > `-XX:FreqInlineSize=325` + + +`-XX:MaxInlineSize=`*size* +: Sets the maximum bytecode size (in bytes) of a cold method to be inlined. + This flag only applies to the C2 compiler. + Append the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate + megabytes, or `g` or `G` to indicate gigabytes. By default, the maximum + bytecode size is set to 35 bytes: + + > `-XX:MaxInlineSize=35` + +`-XX:C1MaxInlineSize=`*size* +: Sets the maximum bytecode size (in bytes) of a cold method to be inlined. + This flag only applies to the C1 compiler. + Append the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate + megabytes, or `g` or `G` to indicate gigabytes. By default, the maximum + bytecode size is set to 35 bytes: + + > `-XX:MaxInlineSize=35` + +`-XX:MaxTrivialSize=`*size* +: Sets the maximum bytecode size (in bytes) of a trivial method to be + inlined. This flag only applies to the C2 compiler. + Append the letter `k` or `K` to indicate kilobytes, `m` or `M` to + indicate megabytes, or `g` or `G` to indicate gigabytes. By default, the + maximum bytecode size of a trivial method is set to 6 bytes: + + > `-XX:MaxTrivialSize=6` + +`-XX:C1MaxTrivialSize=`*size* +: Sets the maximum bytecode size (in bytes) of a trivial method to be + inlined. This flag only applies to the C1 compiler. + Append the letter `k` or `K` to indicate kilobytes, `m` or `M` to + indicate megabytes, or `g` or `G` to indicate gigabytes. By default, the + maximum bytecode size of a trivial method is set to 6 bytes: + + > `-XX:MaxTrivialSize=6` + +`-XX:MaxNodeLimit=`*nodes* +: Sets the maximum number of nodes to be used during single method + compilation. By default the value depends on the features enabled. + In the following example the maximum number of nodes is set to 100,000: + + > `-XX:MaxNodeLimit=100000` + +`-XX:NonNMethodCodeHeapSize=`*size* +: Sets the size in bytes of the code segment containing nonmethod code. + + A nonmethod code segment containing nonmethod code, such as compiler + buffers and the bytecode interpreter. This code type stays in the code + cache forever. This flag is used only if `-XX:SegmentedCodeCache` is + enabled. + +`-XX:NonProfiledCodeHeapSize=`*size* +: Sets the size in bytes of the code segment containing nonprofiled methods. + This flag is used only if `-XX:SegmentedCodeCache` is enabled. + +`-XX:+OptimizeStringConcat` +: Enables the optimization of `String` concatenation operations. This option + is enabled by default. To disable the optimization of `String` + concatenation operations, specify `-XX:-OptimizeStringConcat`. + +`-XX:+PrintAssembly` +: Enables printing of assembly code for bytecoded and native methods by using + the external `hsdis-.so` or `.dll` library. For 64-bit VM on Windows, + it's `hsdis-amd64.dll`. This lets you to see the generated code, which may + help you to diagnose performance issues. + + By default, this option is disabled and assembly code isn't printed. The + `-XX:+PrintAssembly` option has to be used together with the + `-XX:UnlockDiagnosticVMOptions` option that unlocks diagnostic JVM options. + +`-XX:ProfiledCodeHeapSize=`*size* +: Sets the size in bytes of the code segment containing profiled methods. + This flag is used only if `-XX:SegmentedCodeCache` is enabled. + +`-XX:+PrintCompilation` +: Enables verbose diagnostic output from the JVM by printing a message to the + console every time a method is compiled. This lets you to see which methods + actually get compiled. By default, this option is disabled and diagnostic + output isn't printed. + + You can also log compilation activity to a file by using the + `-XX:+LogCompilation` option. + +`-XX:+PrintInlining` +: Enables printing of inlining decisions. This let's you see which methods + are getting inlined. + + By default, this option is disabled and inlining information isn't printed. + The `-XX:+PrintInlining` option has to be used together with the + `-XX:+UnlockDiagnosticVMOptions` option that unlocks diagnostic JVM + options. + +`-XX:ReservedCodeCacheSize=`*size* +: Sets the maximum code cache size (in bytes) for JIT-compiled code. Append + the letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate + megabytes, or `g` or `G` to indicate gigabytes. The default maximum code + cache size is 240 MB; if you disable tiered compilation with the option + `-XX:-TieredCompilation`, then the default size is 48 MB. This option has a + limit of 2 GB; otherwise, an error is generated. The maximum code cache + size shouldn't be less than the initial code cache size; see the option + `-XX:InitialCodeCacheSize`. + +`-XX:+SegmentedCodeCache` +: Enables segmentation of the code cache, without which the code cache + consists of one large segment. With `-XX:+SegmentedCodeCache`, separate + segments will be used for non-method, profiled method, and non-profiled + method code. The segments are not resized at runtime. The advantages are + better control of the memory footprint, reduced code fragmentation, and + better CPU iTLB (instruction translation lookaside buffer) and instruction + cache behavior due to improved locality. + + The feature is enabled by default if tiered compilation is enabled + (`-XX:+TieredCompilation` ) and the reserved code cache size + (`-XX:ReservedCodeCacheSize`) is at least 240 MB. + +`-XX:StartAggressiveSweepingAt=`*percent* +: Forces stack scanning of active methods to aggressively remove unused code + when only the given percentage of the code cache is free. The default value + is 10%. + +`-XX:-TieredCompilation` +: Disables the use of tiered compilation. By default, this option is enabled. + +`-XX:UseSSE=`*version* +: Enables the use of SSE instruction set of a specified version. + Is set by default to the highest supported version available (x86 only). + +`-XX:UseAVX=`*version* +: Enables the use of AVX instruction set of a specified version. + Is set by default to the highest supported version available (x86 only). + +`-XX:+UseAES` +: Enables hardware-based AES intrinsics for hardware that supports it. + This option is on by default on hardware that has the necessary instructions. + The `-XX:+UseAES` is used in conjunction with `UseAESIntrinsics`. Flags + that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseAESIntrinsics` +: Enables AES intrinsics. Specifying `-XX:+UseAESIntrinsics` is equivalent to + also enabling `-XX:+UseAES`. To disable hardware-based AES intrinsics, + specify `-XX:-UseAES -XX:-UseAESIntrinsics`. For example, to enable hardware + AES, use the following flags: + + > `-XX:+UseAES -XX:+UseAESIntrinsics` + + Flags that control intrinsics now require the option + `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseAESCTRIntrinsics` +: Analogous to `-XX:+UseAESIntrinsics` enables AES/CTR intrinsics. + +`-XX:+UseGHASHIntrinsics` +: Controls the use of GHASH intrinsics. Enabled by default on platforms that + support the corresponding instructions. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseChaCha20Intrinsics` +: Enable ChaCha20 intrinsics. This option is on by default for supported + platforms. To disable ChaCha20 intrinsics, specify + `-XX:-UseChaCha20Intrinsics`. Flags that control intrinsics now require + the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UsePoly1305Intrinsics` +: Enable Poly1305 intrinsics. This option is on by default for supported + platforms. To disable Poly1305 intrinsics, specify + `-XX:-UsePoly1305Intrinsics`. Flags that control intrinsics now require + the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseBASE64Intrinsics` +: Controls the use of accelerated BASE64 encoding routines for `java.util.Base64`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseAdler32Intrinsics` +: Controls the use of Adler32 checksum algorithm intrinsic for `java.util.zip.Adler32`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseCRC32Intrinsics` +: Controls the use of CRC32 intrinsics for `java.util.zip.CRC32`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseCRC32CIntrinsics` +: Controls the use of CRC32C intrinsics for `java.util.zip.CRC32C`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseSHA` +: Enables hardware-based intrinsics for SHA crypto hash functions for some + hardware. The `UseSHA` option is used in conjunction with the + `UseSHA1Intrinsics`, `UseSHA256Intrinsics`, and `UseSHA512Intrinsics` + options. + + The `UseSHA` and `UseSHA*Intrinsics` flags are enabled by default on + machines that support the corresponding instructions. + + This feature is applicable only when using the `sun.security.provider.Sun` + provider for SHA operations. Flags that control intrinsics now require the + option `-XX:+UnlockDiagnosticVMOptions`. + + To disable all hardware-based SHA intrinsics, specify the `-XX:-UseSHA`. To + disable only a particular SHA intrinsic, use the appropriate corresponding + option. For example: `-XX:-UseSHA256Intrinsics`. + +`-XX:+UseSHA1Intrinsics` +: Enables intrinsics for SHA-1 crypto hash function. Flags that control + intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseSHA256Intrinsics` +: Enables intrinsics for SHA-224 and SHA-256 crypto hash functions. Flags + that control intrinsics now require the option + `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseSHA512Intrinsics` +: Enables intrinsics for SHA-384 and SHA-512 crypto hash functions. Flags + that control intrinsics now require the option + `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseMathExactIntrinsics` +: Enables intrinsification of various `java.lang.Math.*Exact()` functions. + Enabled by default. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseMultiplyToLenIntrinsic` +: Enables intrinsification of `BigInteger.multiplyToLen()`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +-XX:+UseSquareToLenIntrinsic +: Enables intrinsification of `BigInteger.squareToLen()`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +-XX:+UseMulAddIntrinsic +: Enables intrinsification of `BigInteger.mulAdd()`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +-XX:+UseMontgomeryMultiplyIntrinsic +: Enables intrinsification of `BigInteger.montgomeryMultiply()`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +-XX:+UseMontgomerySquareIntrinsic +: Enables intrinsification of `BigInteger.montgomerySquare()`. + Enabled by default on platforms that support it. + Flags that control intrinsics now require the option `-XX:+UnlockDiagnosticVMOptions`. + +`-XX:+UseCMoveUnconditionally` +: Generates CMove (scalar and vector) instructions regardless of + profitability analysis. + +`-XX:+UseCodeCacheFlushing` +: Enables flushing of the code cache before shutting down the compiler. This + option is enabled by default. To disable flushing of the code cache before + shutting down the compiler, specify `-XX:-UseCodeCacheFlushing`. + +`-XX:+UseCondCardMark` +: Enables checking if the card is already marked before updating the card + table. This option is disabled by default. It should be used only on + machines with multiple sockets, where it increases the performance of Java + applications that rely on concurrent operations. + +`-XX:+UseCountedLoopSafepoints` +: Keeps safepoints in counted loops. Its default value depends on whether the + selected garbage collector requires low latency safepoints. + +`-XX:LoopStripMiningIter=`*number_of_iterations* +: Controls the number of iterations in the inner strip mined loop. Strip mining + transforms counted loops into two level nested loops. Safepoints are kept + in the outer loop while the inner loop can execute at full speed. This option + controls the maximum number of iterations in the inner loop. The default value + is 1,000. + +`-XX:LoopStripMiningIterShortLoop=`*number_of_iterations* +: Controls loop strip mining optimization. Loops with the number of iterations + less than specified will not have safepoints in them. Default value is + 1/10th of `-XX:LoopStripMiningIter`. + +`-XX:+UseFMA` +: Enables hardware-based FMA intrinsics for hardware where FMA instructions + are available (such as, Intel and ARM64). FMA intrinsics are + generated for the `java.lang.Math.fma(`*a*`,` *b*`,` *c*`)` methods that + calculate the value of `(` *a* `*` *b* `+` *c* `)` expressions. + +`-XX:+UseSuperWord` +: Enables the transformation of scalar operations into superword operations. + Superword is a vectorization optimization. This option is enabled by + default. To disable the transformation of scalar operations into superword + operations, specify `-XX:-UseSuperWord`. + +## Advanced Serviceability Options for Java + +These `java` options provide the ability to gather system information and +perform extensive debugging. + +`-XX:+DisableAttachMechanism` +: Disables the mechanism that lets tools attach to the JVM. By default, this + option is disabled, meaning that the attach mechanism is enabled and you + can use diagnostics and troubleshooting tools such as `jcmd`, `jstack`, + `jmap`, and `jinfo`. + + > **Note:** The tools such as [jcmd](jcmd.html), [jinfo](jinfo.html), + [jmap](jmap.html), and [jstack](jstack.html) shipped with the JDK aren't + supported when using the tools from one JDK version to troubleshoot a + different JDK version. + +`-XX:+DTraceAllocProbes` +: **Linux and macOS:** Enable `dtrace` tool probes for object allocation. + +`-XX:+DTraceMethodProbes` +: **Linux and macOS:** Enable `dtrace` tool probes for method-entry + and method-exit. + +`-XX:+DTraceMonitorProbes` +: **Linux and macOS:** Enable `dtrace` tool probes for monitor events. + +`-XX:+HeapDumpOnOutOfMemoryError` +: Enables the dumping of the Java heap to a file in the current directory by + using the heap profiler (HPROF) when a `java.lang.OutOfMemoryError` + exception is thrown. You can explicitly set the heap dump file path and + name using the `-XX:HeapDumpPath` option. By default, this option is + disabled and the heap isn't dumped when an `OutOfMemoryError` exception is + thrown. + +`-XX:HeapDumpPath=`*path* +: Sets the path and file name for writing the heap dump provided by the heap + profiler (HPROF) when the `-XX:+HeapDumpOnOutOfMemoryError` option is set. + By default, the file is created in the current working directory, and it's + named `java_pid.hprof` where `` is the identifier of the process + that caused the error. The following example shows how to set the default + file explicitly (`%p` represents the current process identifier): + + > `-XX:HeapDumpPath=./java_pid%p.hprof` + + - **Non-Windows:** The following example shows how to + set the heap dump file to `/var/log/java/java_heapdump.hprof`: + + > `-XX:HeapDumpPath=/var/log/java/java_heapdump.hprof` + + - **Windows:** The following example shows how to set the heap dump file + to `C:/log/java/java_heapdump.log`: + + > `-XX:HeapDumpPath=C:/log/java/java_heapdump.log` + +`-XX:LogFile=`*path* +: Sets the path and file name to where log data is written. By default, the + file is created in the current working directory, and it's named + `hotspot.log`. + + - **Non-Windows:** The following example shows how to + set the log file to `/var/log/java/hotspot.log`: + + > `-XX:LogFile=/var/log/java/hotspot.log` + + - **Windows:** The following example shows how to set the log file to + `C:/log/java/hotspot.log`: + + > `-XX:LogFile=C:/log/java/hotspot.log` + +`-XX:+PrintClassHistogram` +: Enables printing of a class instance histogram after one of the following + events: + + - **Non-Windows:** `Control+\` (`SIGQUIT`) + + - **Windows:** `Control+C` (`SIGTERM`) + + By default, this option is disabled. + + Setting this option is equivalent to running the `jmap -histo` command, or + the `jcmd` *pid* `GC.class_histogram` command, where *pid* is the current + Java process identifier. + +`-XX:+PrintConcurrentLocks` +: Enables printing of `java.util.concurrent` locks after one of the following + events: + + - **Non-Windows:** `Control+\` (`SIGQUIT`) + + - **Windows:** `Control+C` (`SIGTERM`) + + By default, this option is disabled. + + Setting this option is equivalent to running the `jstack -l` command or the + `jcmd` *pid* `Thread.print -l` command, where *pid* is the current Java + process identifier. + +`-XX:+PrintFlagsRanges` +: Prints the range specified and allows automatic testing of the values. See + [Validate Java Virtual Machine Flag + Arguments]. + +`-XX:+PerfDataSaveToFile` +: If enabled, saves [jstat](jstat.html) binary data when the Java application + exits. This binary data is saved in a file named `hsperfdata_`*pid*, where + *pid* is the process identifier of the Java application that you ran. Use + the `jstat` command to display the performance data contained in this file + as follows: + + > `jstat -class file:///`*path*`/hsperfdata_`*pid* + + > `jstat -gc file:///`*path*`/hsperfdata_`*pid* + +`-XX:+UsePerfData` +: Enables the `perfdata` feature. This option is enabled by default to allow + JVM monitoring and performance testing. Disabling it suppresses the + creation of the `hsperfdata_userid` directories. To disable the `perfdata` + feature, specify `-XX:-UsePerfData`. + +## Advanced Garbage Collection Options for Java + +These `java` options control how garbage collection (GC) is performed by the +Java HotSpot VM. + +`-XX:+AggressiveHeap` +: Enables Java heap optimization. This sets various parameters to be + optimal for long-running jobs with intensive memory allocation, based on + the configuration of the computer (RAM and CPU). By default, the option + is disabled and the heap sizes are configured less aggressively. + +`-XX:+AlwaysPreTouch` +: Requests the VM to touch every page on the Java heap after requesting it from + the operating system and before handing memory out to the application. + By default, this option is disabled and all pages are committed as the + application uses the heap space. + +`-XX:ConcGCThreads=`*threads* +: Sets the number of threads used for concurrent GC. Sets *`threads`* to + approximately 1/4 of the number of parallel garbage collection threads. The + default value depends on the number of CPUs available to the JVM. + + For example, to set the number of threads for concurrent GC to 2, specify + the following option: + + > `-XX:ConcGCThreads=2` + +`-XX:+DisableExplicitGC` +: Enables the option that disables processing of calls to the `System.gc()` + method. This option is disabled by default, meaning that calls to + `System.gc()` are processed. If processing of calls to `System.gc()` is + disabled, then the JVM still performs GC when necessary. + +`-XX:+ExplicitGCInvokesConcurrent` +: Enables invoking of concurrent GC by using the `System.gc()` request. This + option is disabled by default and can be enabled only with the `-XX:+UseG1GC` option. + +`-XX:G1AdaptiveIHOPNumInitialSamples=`*number* +: When `-XX:UseAdaptiveIHOP` is enabled, this option sets the number of + completed marking cycles used to gather samples until G1 adaptively + determines the optimum value of `-XX:InitiatingHeapOccupancyPercent`. Before, + G1 uses the value of `-XX:InitiatingHeapOccupancyPercent` directly for + this purpose. The default value is 3. + +`-XX:G1HeapRegionSize=`*size* +: Sets the size of the regions into which the Java heap is subdivided when + using the garbage-first (G1) collector. The value is a power of 2 and can + range from 1 MB to 32 MB. The default region size is determined + ergonomically based on the heap size with a goal of approximately 2048 + regions. + + The following example sets the size of the subdivisions to 16 MB: + + > `-XX:G1HeapRegionSize=16m` + +`-XX:G1HeapWastePercent=`*percent* +: Sets the percentage of heap that you're willing to waste. The Java HotSpot + VM doesn't initiate the mixed garbage collection cycle when the reclaimable + percentage is less than the heap waste percentage. The default is 5 + percent. + +`-XX:G1MaxNewSizePercent=`*percent* +: Sets the percentage of the heap size to use as the maximum for the young + generation size. The default value is 60 percent of your Java heap. + + This is an experimental flag. This setting replaces the + `-XX:DefaultMaxNewGenPercent` setting. + +`-XX:G1MixedGCCountTarget=`*number* +: Sets the target number of mixed garbage collections after a marking cycle + to collect old regions with at most `G1MixedGCLIveThresholdPercent` live + data. The default is 8 mixed garbage collections. The goal for mixed + collections is to be within this target number. + +`-XX:G1MixedGCLiveThresholdPercent=`*percent* +: Sets the occupancy threshold for an old region to be included in a mixed + garbage collection cycle. The default occupancy is 85 percent. + + This is an experimental flag. This setting replaces the + `-XX:G1OldCSetRegionLiveThresholdPercent` setting. + +`-XX:G1NewSizePercent=`*percent* +: Sets the percentage of the heap to use as the minimum for the young + generation size. The default value is 5 percent of your Java heap. + + This is an experimental flag. This setting replaces the + `-XX:DefaultMinNewGenPercent` setting. + +`-XX:G1OldCSetRegionThresholdPercent=`*percent* +: Sets an upper limit on the number of old regions to be collected during a + mixed garbage collection cycle. The default is 10 percent of the Java heap. + +`-XX:G1ReservePercent=`*percent* +: Sets the percentage of the heap (0 to 50) that's reserved as a false + ceiling to reduce the possibility of promotion failure for the G1 + collector. When you increase or decrease the percentage, ensure that you + adjust the total Java heap by the same amount. By default, this option is + set to 10%. + + The following example sets the reserved heap to 20%: + + > `-XX:G1ReservePercent=20` + +`-XX:+G1UseAdaptiveIHOP` +: Controls adaptive calculation of the old generation occupancy to start + background work preparing for an old generation collection. If enabled, + G1 uses `-XX:InitiatingHeapOccupancyPercent` for the first few times as + specified by the value of `-XX:G1AdaptiveIHOPNumInitialSamples`, and after + that adaptively calculates a new optimum value for the initiating + occupancy automatically. + Otherwise, the old generation collection process always starts at the + old generation occupancy determined by + `-XX:InitiatingHeapOccupancyPercent`. + + The default is enabled. + +`-XX:InitialHeapSize=`*size* +: Sets the initial size (in bytes) of the memory allocation pool. This value + must be either 0, or a multiple of 1024 and greater than 1 MB. Append the + letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate megabytes, + or `g` or `G` to indicate gigabytes. The default value is selected at run + time based on the system configuration. + + The following examples show how to set the size of allocated memory to 6 MB + using various units: + + ``` + -XX:InitialHeapSize=6291456 + -XX:InitialHeapSize=6144k + -XX:InitialHeapSize=6m + ``` + + If you set this option to 0, then the initial size is set as the sum of the + sizes allocated for the old generation and the young generation. The size + of the heap for the young generation can be set using the `-XX:NewSize` + option. Note that the `-Xms` option sets both the minimum and the initial + heap size of the heap. If `-Xms` appears after `-XX:InitialHeapSize` on the + command line, then the initial heap size gets set to the value specified + with `-Xms`. + +`-XX:InitialRAMPercentage=`*percent* +: Sets the initial amount of memory that the JVM will use for the Java heap + before applying ergonomics heuristics as a percentage of the maximum amount + determined as described in the `-XX:MaxRAM` option. The default value is + 1.5625 percent. + + The following example shows how to set the percentage of the initial + amount of memory used for the Java heap: + + > `-XX:InitialRAMPercentage=5` + +`-XX:InitialSurvivorRatio=`*ratio* +: Sets the initial survivor space ratio used by the throughput garbage + collector (which is enabled by the `-XX:+UseParallelGC` option). Adaptive + sizing is enabled by default with the throughput garbage collector by + using the `-XX:+UseParallelGC` option, and the survivor space is resized + according to the application behavior, starting with the initial value. If + adaptive sizing is disabled (using the `-XX:-UseAdaptiveSizePolicy` + option), then the `-XX:SurvivorRatio` option should be used to set the size + of the survivor space for the entire execution of the application. + + The following formula can be used to calculate the initial size of survivor + space (S) based on the size of the young generation (Y), and the initial + survivor space ratio (R): + + > `S=Y/(R+2)` + + The 2 in the equation denotes two survivor spaces. The larger the value + specified as the initial survivor space ratio, the smaller the initial + survivor space size. + + By default, the initial survivor space ratio is set to 8. If the default + value for the young generation space size is used (2 MB), then the initial + size of the survivor space is 0.2 MB. + + The following example shows how to set the initial survivor space ratio to + 4: + + > `-XX:InitialSurvivorRatio=4` + +`-XX:InitiatingHeapOccupancyPercent=`*percent* +: Sets the percentage of the old generation occupancy (0 to 100) at which to + start the first few concurrent marking cycles for the G1 garbage collector. + + By default, the initiating value is set to 45%. A value of 0 implies + nonstop concurrent GC cycles from the beginning until G1 adaptively sets this + value. + + See also the `-XX:G1UseAdaptiveIHOP` and `-XX:G1AdaptiveIHOPNumInitialSamples` + options. + + The following example shows how to set the initiating heap occupancy to 75%: + + > `-XX:InitiatingHeapOccupancyPercent=75` + +`-XX:MaxGCPauseMillis=`*time* +: Sets a target for the maximum GC pause time (in milliseconds). This is a + soft goal, and the JVM will make its best effort to achieve it. The + specified value doesn't adapt to your heap size. By default, for G1 the + maximum pause time target is 200 milliseconds. The other generational + collectors do not use a pause time goal by default. + + The following example shows how to set the maximum target pause time to 500 + ms: + + > `-XX:MaxGCPauseMillis=500` + +`-XX:MaxHeapSize=`*size* +: Sets the maximum size (in byes) of the memory allocation pool. This value + must be a multiple of 1024 and greater than 2 MB. Append the letter `k` or + `K` to indicate kilobytes, `m` or `M` to indicate megabytes, or `g` or `G` + to indicate gigabytes. The default value is selected at run time based on + the system configuration. For server deployments, the options + `-XX:InitialHeapSize` and `-XX:MaxHeapSize` are often set to the same + value. + + The following examples show how to set the maximum allowed size of + allocated memory to 80 MB using various units: + + ``` + -XX:MaxHeapSize=83886080 + -XX:MaxHeapSize=81920k + -XX:MaxHeapSize=80m + ``` + + The `-XX:MaxHeapSize` option is equivalent to `-Xmx`. + +`-XX:MaxHeapFreeRatio=`*percent* +: Sets the maximum allowed percentage of free heap space (0 to 100) after a + GC event. If free heap space expands above this value, then the heap is + shrunk. By default, this value is set to 70%. + + Minimize the Java heap size by lowering the values of the parameters + `MaxHeapFreeRatio` (default value is 70%) and `MinHeapFreeRatio` (default + value is 40%) with the command-line options `-XX:MaxHeapFreeRatio` and + `-XX:MinHeapFreeRatio`. Lowering `MaxHeapFreeRatio` to as low as 10% and + `MinHeapFreeRatio` to 5% has successfully reduced the heap size without too + much performance regression; however, results may vary greatly depending on + your application. Try different values for these parameters until they're + as low as possible yet still retain acceptable performance. + + > `-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5` + + Customers trying to keep the heap small should also add the option + `-XX:-ShrinkHeapInSteps`. See [Performance Tuning Examples] for a + description of using this option to keep the Java heap small by reducing + the dynamic footprint for embedded applications. + +`-XX:MaxMetaspaceSize=`*size* +: Sets the maximum amount of native memory that can be allocated for class + metadata. By default, the size isn't limited. The amount of metadata for an + application depends on the application itself, other running applications, + and the amount of memory available on the system. + + The following example shows how to set the maximum class metadata size to + 256 MB: + + > `-XX:MaxMetaspaceSize=256m` + +`-XX:MaxNewSize=`*size* +: Sets the maximum size (in bytes) of the heap for the young generation + (nursery). The default value is set ergonomically. + +`-XX:MaxRAM=`*size* +: Sets the maximum amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics. The default value is the maximum + amount of available memory to the JVM process or 128 GB, whichever is lower. + + The maximum amount of available memory to the JVM process is the minimum + of the machine's physical memory and any constraints set by the environment + (e.g. container). + + Specifying this option disables automatic use of compressed oops if + the combined result of this and other options influencing the maximum amount + of memory is larger than the range of memory addressable by compressed oops. + See `-XX:UseCompressedOops` for further information about compressed oops. + + The following example shows how to set the maximum amount of available + memory for sizing the Java heap to 2 GB: + + > `-XX:MaxRAM=2G` + +`-XX:MaxRAMPercentage=`*percent* +: Sets the maximum amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics as a percentage of the maximum amount + determined as described in the `-XX:MaxRAM` option. The default value is 25 + percent. + + Specifying this option disables automatic use of compressed oops if + the combined result of this and other options influencing the maximum amount + of memory is larger than the range of memory addressable by compressed oops. + See `-XX:UseCompressedOops` for further information about compressed oops. + + The following example shows how to set the percentage of the maximum amount + of memory used for the Java heap: + + > `-XX:MaxRAMPercentage=75` + +`-XX:MinRAMPercentage=`*percent* +: Sets the maximum amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics as a percentage of the maximum amount + determined as described in the `-XX:MaxRAM` option for small heaps. A small + heap is a heap of approximately 125 MB. The default value is 50 percent. + + The following example shows how to set the percentage of the maximum amount + of memory used for the Java heap for small heaps: + + > `-XX:MinRAMPercentage=75` + +`-XX:MaxTenuringThreshold=`*threshold* +: Sets the maximum tenuring threshold for use in adaptive GC sizing. The + largest value is 15. The default value is 15 for the parallel (throughput) + collector. + + The following example shows how to set the maximum tenuring threshold to + 10: + + > `-XX:MaxTenuringThreshold=10` + +`-XX:MetaspaceSize=`*size* +: Sets the size of the allocated class metadata space that triggers a garbage + collection the first time it's exceeded. This threshold for a garbage + collection is increased or decreased depending on the amount of metadata + used. The default size depends on the platform. + +`-XX:MinHeapFreeRatio=`*percent* +: Sets the minimum allowed percentage of free heap space (0 to 100) after a + GC event. If free heap space falls below this value, then the heap is + expanded. By default, this value is set to 40%. + + Minimize Java heap size by lowering the values of the parameters + `MaxHeapFreeRatio` (default value is 70%) and `MinHeapFreeRatio` (default + value is 40%) with the command-line options `-XX:MaxHeapFreeRatio` and + `-XX:MinHeapFreeRatio`. Lowering `MaxHeapFreeRatio` to as low as 10% and + `MinHeapFreeRatio` to 5% has successfully reduced the heap size without too + much performance regression; however, results may vary greatly depending on + your application. Try different values for these parameters until they're + as low as possible, yet still retain acceptable performance. + + > `-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5` + + Customers trying to keep the heap small should also add the option + `-XX:-ShrinkHeapInSteps`. See [Performance Tuning Examples] for a + description of using this option to keep the Java heap small by reducing + the dynamic footprint for embedded applications. + +`-XX:MinHeapSize=`*size* +: Sets the minimum size (in bytes) of the memory allocation pool. This value + must be either 0, or a multiple of 1024 and greater than 1 MB. Append the + letter `k` or `K` to indicate kilobytes, `m` or `M` to indicate megabytes, + or `g` or `G` to indicate gigabytes. The default value is selected at run + time based on the system configuration. + + The following examples show how to set the minimum size of allocated memory + to 6 MB using various units: + + ``` + -XX:MinHeapSize=6291456 + -XX:MinHeapSize=6144k + -XX:MinHeapSize=6m + ``` + + If you set this option to 0, then the minimum size is set to the same value + as the initial size. + +`-XX:NewRatio=`*ratio* +: Sets the ratio between young and old generation sizes. By default, this + option is set to 2. The following example shows how to set the young-to-old + ratio to 1: + + > `-XX:NewRatio=1` + +`-XX:NewSize=`*size* +: Sets the initial size (in bytes) of the heap for the young generation + (nursery). Append the letter `k` or `K` to indicate kilobytes, `m` or `M` + to indicate megabytes, or `g` or `G` to indicate gigabytes. + + The young generation region of the heap is used for new objects. GC is + performed in this region more often than in other regions. If the size for + the young generation is too low, then a large number of minor GCs are + performed. If the size is too high, then only full GCs are performed, which + can take a long time to complete. It is recommended that you keep the size + for the young generation greater than 25% and less than 50% of the overall + heap size. + + The following examples show how to set the initial size of the young + generation to 256 MB using various units: + + ``` + -XX:NewSize=256m + -XX:NewSize=262144k + -XX:NewSize=268435456 + ``` + + The `-XX:NewSize` option is equivalent to `-Xmn`. + +`-XX:ParallelGCThreads=`*threads* +: Sets the number of the stop-the-world (STW) worker threads. The default value + depends on the number of CPUs available to the JVM and the garbage collector + selected. + + For example, to set the number of threads for G1 GC to 2, specify the + following option: + + > `-XX:ParallelGCThreads=2` + +`-XX:+ParallelRefProcEnabled` +: Enables parallel reference processing. By default, this option is disabled. + +`-XX:+PrintAdaptiveSizePolicy` +: Enables printing of information about adaptive-generation sizing. By + default, this option is disabled. + +`-XX:SoftRefLRUPolicyMSPerMB=`*time* +: Sets the amount of time (in milliseconds) a softly reachable object is + kept active on the heap after the last time it was referenced. The default + value is one second of lifetime per free megabyte in the heap. The + `-XX:SoftRefLRUPolicyMSPerMB` option accepts integer values representing + milliseconds per one megabyte of the current heap size (for Java HotSpot + Client VM) or the maximum possible heap size (for Java HotSpot Server VM). + This difference means that the Client VM tends to flush soft references + rather than grow the heap, whereas the Server VM tends to grow the heap + rather than flush soft references. In the latter case, the value of the + `-Xmx` option has a significant effect on how quickly soft references are + garbage collected. + + The following example shows how to set the value to 2.5 seconds: + + `-XX:SoftRefLRUPolicyMSPerMB=2500` + +`-XX:-ShrinkHeapInSteps` +: Incrementally reduces the Java heap to the target size, specified by the + option `-XX:MaxHeapFreeRatio`. This option is enabled by default. If + disabled, then it immediately reduces the Java heap to the target size + instead of requiring multiple garbage collection cycles. Disable this + option if you want to minimize the Java heap size. You will likely + encounter performance degradation when this option is disabled. + + See [Performance Tuning Examples] for a description of using the + `MaxHeapFreeRatio` option to keep the Java heap small by reducing the + dynamic footprint for embedded applications. + +`-XX:StringDeduplicationAgeThreshold=`*threshold* +: Identifies `String` objects reaching the specified age that are considered + candidates for deduplication. An object's age is a measure of how many + times it has survived garbage collection. This is sometimes referred to as + tenuring. + + > **Note:** `String` objects that are promoted to an old heap region before this age + has been reached are always considered candidates for deduplication. The + default value for this option is `3`. See the `-XX:+UseStringDeduplication` + option. + +`-XX:SurvivorRatio=`*ratio* +: Sets the ratio between eden space size and survivor space size. By default, + this option is set to 8. The following example shows how to set the + eden/survivor space ratio to 4: + + > `-XX:SurvivorRatio=4` + +`-XX:TargetSurvivorRatio=`*percent* +: Sets the desired percentage of survivor space (0 to 100) used after young + garbage collection. By default, this option is set to 50%. + + The following example shows how to set the target survivor space ratio to + 30%: + + > `-XX:TargetSurvivorRatio=30` + +`-XX:TLABSize=`*size* +: Sets the initial size (in bytes) of a thread-local allocation buffer + (TLAB). Append the letter `k` or `K` to indicate kilobytes, `m` or `M` to + indicate megabytes, or `g` or `G` to indicate gigabytes. If this option is + set to 0, then the JVM selects the initial size automatically. + + The following example shows how to set the initial TLAB size to 512 KB: + + > `-XX:TLABSize=512k` + +`-XX:+UseAdaptiveSizePolicy` +: Enables the use of adaptive generation sizing. This option is enabled by + default. To disable adaptive generation sizing, specify + `-XX:-UseAdaptiveSizePolicy` and set the size of the memory allocation pool + explicitly. See the `-XX:SurvivorRatio` option. + +`-XX:+UseG1GC` +: Enables the use of the garbage-first (G1) garbage collector. It's a + server-style garbage collector, targeted for multiprocessor machines with a + large amount of RAM. This option meets GC pause time goals with high + probability, while maintaining good throughput. The G1 collector is + recommended for applications requiring large heaps (sizes of around 6 GB or + larger) with limited GC latency requirements (a stable and predictable + pause time below 0.5 seconds). By default, this option is enabled and G1 is + used as the default garbage collector. + +`-XX:+UseGCOverheadLimit` +: Enables the use of a policy that limits the proportion of time spent by the + JVM on GC before an `OutOfMemoryError` exception is thrown. This option is + enabled, by default, and the parallel GC will throw an `OutOfMemoryError` + if more than 98% of the total time is spent on garbage collection and less + than 2% of the heap is recovered. When the heap is small, this feature can + be used to prevent applications from running for long periods of time with + little or no progress. To disable this option, specify the option + `-XX:-UseGCOverheadLimit`. + +`-XX:+UseNUMA` +: Enables performance optimization of an application on a machine with + nonuniform memory architecture (NUMA) by increasing the application's use + of lower latency memory. By default, this option is disabled and no + optimization for NUMA is made. The option is available only when the + parallel garbage collector is used (`-XX:+UseParallelGC`). + +`-XX:+UseParallelGC` +: Enables the use of the parallel scavenge garbage collector (also known as + the throughput collector) to improve the performance of your application by + leveraging multiple processors. + + By default, this option is disabled and the default collector is used. + +`-XX:+UseSerialGC` +: Enables the use of the serial garbage collector. This is generally the best + choice for small and simple applications that don't require any special + functionality from garbage collection. By default, this option is disabled + and the default collector is used. + +`-XX:+UseStringDeduplication` +: Enables string deduplication. By default, this option is disabled. To use + this option, you must enable the garbage-first (G1) garbage collector. + + String deduplication reduces the memory footprint of `String` objects on + the Java heap by taking advantage of the fact that many `String` objects + are identical. Instead of each `String` object pointing to its own + character array, identical `String` objects can point to and share the same + character array. + +`-XX:+UseTLAB` +: Enables the use of thread-local allocation blocks (TLABs) in the young + generation space. This option is enabled by default. To disable the use of + TLABs, specify the option `-XX:-UseTLAB`. + +`-XX:+UseZGC` +: Enables the use of the Z garbage collector (ZGC). This is a low latency + garbage collector, providing max pause times of a few milliseconds, at + some throughput cost. Pause times are independent of what heap size is + used. Supports heap sizes from 8MB to 16TB. + +`-XX:ZAllocationSpikeTolerance=`*factor* +: Sets the allocation spike tolerance for ZGC. By default, this option is + set to 2.0. This factor describes the level of allocation spikes to expect. + For example, using a factor of 3.0 means the current allocation rate can + be expected to triple at any time. + +`-XX:ZCollectionInterval=`*seconds* +: Sets the maximum interval (in seconds) between two GC cycles when using + ZGC. By default, this option is set to 0 (disabled). + +`-XX:ZFragmentationLimit=`*percent* +: Sets the maximum acceptable heap fragmentation (in percent) for ZGC. + By default, this option is set to 25. Using a lower value will cause the + heap to be compacted more aggressively, to reclaim more memory at the cost + of using more CPU time. + +`-XX:+ZProactive` +: Enables proactive GC cycles when using ZGC. By default, this option is + enabled. ZGC will start a proactive GC cycle if doing so is expected to + have minimal impact on the running application. This is useful if the + application is mostly idle or allocates very few objects, but you still + want to keep the heap size down and allow reference processing to happen + even when there are a lot of free space on the heap. + +`-XX:+ZUncommit` +: Enables uncommitting of unused heap memory when using ZGC. By default, + this option is enabled. Uncommitting unused heap memory will lower the + memory footprint of the JVM, and make that memory available for other + processes to use. + +`-XX:ZUncommitDelay=`*seconds* +: Sets the amount of time (in seconds) that heap memory must have been + unused before being uncommitted. By default, this option is set to 300 + (5 minutes). Committing and uncommitting memory are relatively + expensive operations. Using a lower value will cause heap memory to be + uncommitted earlier, at the risk of soon having to commit it again. + +## Deprecated Java Options + +These `java` options are deprecated and might be removed in a future JDK +release. They're still accepted and acted upon, but a warning is issued when +they're used. + +`-Xloggc:`*filename* +: Sets the file to which verbose GC events information should be redirected + for logging. The `-Xloggc` option overrides `-verbose:gc` if both are given + with the same java command. `-Xloggc:`*filename* is replaced by + `-Xlog:gc:`*filename*. See Enable Logging with the JVM Unified Logging + Framework. + + Example: + + `-Xlog:gc:garbage-collection.log` + +`-XX:+FlightRecorder` +: Enables the use of Java Flight Recorder (JFR) during the runtime of the + application. Since JDK 8u40 this option has not been required to use JFR. + +## Obsolete Java Options + +These `java` options are still accepted but ignored, and a warning is issued +when they're used. + +`--illegal-access=`*parameter* +: Controlled _relaxed strong encapsulation_, as defined in [JEP + 261](https://openjdk.org/jeps/261#Relaxed-strong-encapsulation). + This option was deprecated in JDK 16 by [JEP + 396](https://openjdk.org/jeps/396) and made obsolete in JDK 17 + by [JEP 403](https://openjdk.org/jeps/403). + +`-XX:RTMAbortRatio=`*abort\_ratio* +: Specifies the RTM abort ratio is specified as a percentage (%) of all + executed RTM transactions. If a number of aborted transactions becomes + greater than this ratio, then the compiled code is deoptimized. This ratio + is used when the `-XX:+UseRTMDeopt` option is enabled. The default value of + this option is 50. This means that the compiled code is deoptimized if 50% + of all transactions are aborted. + +`-XX:RTMRetryCount=`*number\_of\_retries* +: Specifies the number of times that the RTM locking code is retried, when it + is aborted or busy, before falling back to the normal locking mechanism. + The default value for this option is 5. The `-XX:UseRTMLocking` option must + be enabled. + +`-XX:+UseRTMDeopt` +: Autotunes RTM locking depending on the abort ratio. This ratio is specified + by the `-XX:RTMAbortRatio` option. If the number of aborted transactions + exceeds the abort ratio, then the method containing the lock is deoptimized + and recompiled with all locks as normal locks. This option is disabled by + default. The `-XX:+UseRTMLocking` option must be enabled. + +`-XX:+UseRTMLocking` +: Generates Restricted Transactional Memory (RTM) locking code for all + inflated locks, with the normal locking mechanism as the fallback handler. + This option is disabled by default. Options related to RTM are available + only on x86 CPUs that support Transactional Synchronization Extensions (TSX). + + RTM is part of Intel's TSX, which is an x86 instruction set extension and + facilitates the creation of multithreaded applications. RTM introduces the + new instructions `XBEGIN`, `XABORT`, `XEND`, and `XTEST`. The `XBEGIN` and + `XEND` instructions enclose a set of instructions to run as a transaction. + If no conflict is found when running the transaction, then the memory and + register modifications are committed together at the `XEND` instruction. + The `XABORT` instruction can be used to explicitly abort a transaction and + the `XTEST` instruction checks if a set of instructions is being run in a + transaction. + + A lock on a transaction is inflated when another thread tries to access the + same transaction, thereby blocking the thread that didn't originally + request access to the transaction. RTM requires that a fallback set of + operations be specified in case a transaction aborts or fails. An RTM lock + is a lock that has been delegated to the TSX's system. + + RTM improves performance for highly contended locks with low conflict in a + critical region (which is code that must not be accessed by more than one + thread concurrently). RTM also improves the performance of coarse-grain + locking, which typically doesn't perform well in multithreaded + applications. (Coarse-grain locking is the strategy of holding locks for + long periods to minimize the overhead of taking and releasing locks, while + fine-grained locking is the strategy of trying to achieve maximum + parallelism by locking only when necessary and unlocking as soon as + possible.) Also, for lightly contended locks that are used by different + threads, RTM can reduce false cache line sharing, also known as cache line + ping-pong. This occurs when multiple threads from different processors are + accessing different resources, but the resources share the same cache line. + As a result, the processors repeatedly invalidate the cache lines of other + processors, which forces them to read from main memory instead of their + cache. + +## Removed Java Options + +These `java` options have been removed in JDK @@VERSION_SPECIFICATION@@ and using them results in an error of: + +> `Unrecognized VM option` *option-name* + +`-XX:InitialRAMFraction=`*ratio* +: Sets the initial amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics as a ratio of the maximum amount + determined as described in the `-XX:MaxRAM` option. The default value is + 64. + + Use the option `-XX:InitialRAMPercentage` instead. + +`-XX:MaxRAMFraction=`*ratio* +: Sets the maximum amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics as a fraction of the maximum amount + determined as described in the `-XX:MaxRAM` option. The default value is 4. + + Specifying this option disables automatic use of compressed oops if + the combined result of this and other options influencing the maximum amount + of memory is larger than the range of memory addressable by compressed oops. + See `-XX:UseCompressedOops` for further information about compressed oops. + + Use the option `-XX:MaxRAMPercentage` instead. + +`-XX:MinRAMFraction=`*ratio* +: Sets the maximum amount of memory that the JVM may use for the Java heap + before applying ergonomics heuristics as a fraction of the maximum amount + determined as described in the `-XX:MaxRAM` option for small heaps. A small + heap is a heap of approximately 125 MB. The default value is 2. + + Use the option `-XX:MinRAMPercentage` instead. + +`-XX:+ScavengeBeforeFullGC` +: Enables GC of the young generation before each full GC. This option is + enabled by default. It is recommended that you *don't* disable it, because + scavenging the young generation before a full GC can reduce the number of + objects reachable from the old generation space into the young generation + space. To disable GC of the young generation before each full GC, specify + the option `-XX:-ScavengeBeforeFullGC`. + +`-Xfuture` +: Enables strict class-file format checks that enforce close conformance to + the class-file format specification. Developers should use this flag when + developing new code. Stricter checks may become the default in future + releases. + + Use the option `-Xverify:all` instead. + +For the lists and descriptions of options removed in previous releases see the *Removed Java Options* section in: + +- [The `java` Command, Release 23](https://docs.oracle.com/en/java/javase/23/docs/specs/man/java.html) + +- [The `java` Command, Release 22](https://docs.oracle.com/en/java/javase/22/docs/specs/man/java.html) + +- [The `java` Command, Release 21](https://docs.oracle.com/en/java/javase/21/docs/specs/man/java.html) + +- [The `java` Command, Release 20](https://docs.oracle.com/en/java/javase/20/docs/specs/man/java.html) + +- [The `java` Command, Release 19](https://docs.oracle.com/en/java/javase/19/docs/specs/man/java.html) + +- [The `java` Command, Release 18](https://docs.oracle.com/en/java/javase/18/docs/specs/man/java.html) + +- [The `java` Command, Release 17](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html) + +- [The `java` Command, Release 16](https://docs.oracle.com/en/java/javase/16/docs/specs/man/java.html) + +- [The `java` Command, Release 15](https://docs.oracle.com/en/java/javase/15/docs/specs/man/java.html) + +- [The `java` Command, Release 14](https://docs.oracle.com/en/java/javase/14/docs/specs/man/java.html) + +- [The `java` Command, Release 13](https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html) + +- [Java Platform, Standard Edition Tools Reference, Release 12]( + https://docs.oracle.com/en/java/javase/12/tools/java.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE) + +- [Java Platform, Standard Edition Tools Reference, Release 11]( + https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1) + +- [Java Platform, Standard Edition Tools Reference, Release 10]( + https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624) + +- [Java Platform, Standard Edition Tools Reference, Release 9]( + https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624) + +- [Java Platform, Standard Edition Tools Reference, Release 8 for Oracle JDK + on Windows]( + https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html#BGBCIEFC) + +- [Java Platform, Standard Edition Tools Reference, Release 8 for Oracle JDK + on Solaris, Linux, and macOS]( + https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC) + +## java Command-Line Argument Files + +You can shorten or simplify the `java` command by using `@` argument files to +specify one or more text files that contain arguments, such as options and +class names, which are passed to the `java` command. This let's you to create +`java` commands of any length on any operating system. + +In the command line, use the at sign (`@`) prefix to identify an argument file +that contains `java` options and class names. When the `java` command +encounters a file beginning with the at sign (`@`), it expands the contents of +that file into an argument list just as they would be specified on the command +line. + +The `java` launcher expands the argument file contents until it encounters the +`--disable-@files` option. You can use the `--disable-@files` option anywhere +on the command line, including in an argument file, to stop `@` argument files +expansion. + +The following items describe the syntax of `java` argument files: + +- The argument file must contain only ASCII characters or characters in + system default encoding that's ASCII friendly, such as UTF-8. + +- The argument file size must not exceed MAXINT (2,147,483,647) bytes. + +- The launcher doesn't expand wildcards that are present within an argument + file. + +- Use white space or new line characters to separate arguments included in + the file. + +- White space includes a white space character, `\t`, `\n`, `\r`, and `\f`. + + For example, it is possible to have a path with a space, such as + `c:\Program Files` that can be specified as either `"c:\\Program Files"` or, + to avoid an escape, `c:\Program" "Files`. + +- Any option that contains spaces, such as a path component, must be within + quotation marks using quotation ('\"') characters in its entirety. + +- A string within quotation marks may contain the characters `\n`, `\r`, + `\t`, and `\f`. They are converted to their respective ASCII codes. + +- If a file name contains embedded spaces, then put the whole file name in + double quotation marks. + +- File names in an argument file are relative to the current directory, not + to the location of the argument file. + +- Use the number sign `#` in the argument file to identify comments. All + characters following the `#` are ignored until the end of line. + +- Additional at sign `@` prefixes to `@` prefixed options act as an escape, + (the first `@` is removed and the rest of the arguments are presented to + the launcher literally). + +- Lines may be continued using the continuation character (`\`) at the + end-of-line. The two lines are concatenated with the leading white spaces + trimmed. To prevent trimming the leading white spaces, a continuation + character (`\`) may be placed at the first column. + +- Because backslash (\\) is an escape character, a backslash character must + be escaped with another backslash character. + +- Partial quote is allowed and is closed by an end-of-file. + +- An open quote stops at end-of-line unless `\` is the last character, which + then joins the next line by removing all leading white space characters. + +- Wildcards (\*) aren't allowed in these lists (such as specifying `*.java`). + +- Use of the at sign (`@`) to recursively interpret files isn't supported. + +### Example of Open or Partial Quotes in an Argument File + +In the argument file, + +``` +-cp "lib/ +cool/ +app/ +jars +``` + +this is interpreted as: + +> `-cp lib/cool/app/jars` + +### Example of a Backslash Character Escaped with Another Backslash Character in an Argument File + +To output the following: + +> `-cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program + Files\Java\jre9\lib\ext` + +The backslash character must be specified in the argument file as: + +> `-cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Program + Files\\Java\\jre9\\lib\\ext"` + +### Example of an EOL Escape Used to Force Concatenation of Lines in an Argument File + +In the argument file, + +``` +-cp "/lib/cool app/jars:\ + /lib/another app/jars" +``` + +This is interpreted as: + +> `-cp /lib/cool app/jars:/lib/another app/jars` + +### Example of Line Continuation with Leading Spaces in an Argument File + +In the argument file, + +``` +-cp "/lib/cool\ +\app/jars" +``` + +This is interpreted as: + +`-cp /lib/cool app/jars` + +### Examples of Using Single Argument File + +You can use a single argument file, such as `myargumentfile` in the following +example, to hold all required `java` arguments: + +> `java @myargumentfile` + +### Examples of Using Argument Files with Paths + +You can include relative paths in argument files; however, they're relative to +the current working directory and not to the paths of the argument files +themselves. In the following example, `path1/options` and `path2/options` +represent argument files with different paths. Any relative paths that they +contain are relative to the current working directory and not to the argument +files: + +> `java @path1/options @path2/classes` + +## Code Heap State Analytics + +### Overview + +There are occasions when having insight into the current state of the JVM code +heap would be helpful to answer questions such as: + +- Why was the JIT turned off and then on again and again? + +- Where has all the code heap space gone? + +- Why is the method sweeper not working effectively? + +To provide this insight, a code heap state analytics feature has been +implemented that enables on-the-fly analysis of the code heap. The analytics +process is divided into two parts. The first part examines the entire code heap +and aggregates all information that is believed to be useful or important. The +second part consists of several independent steps that print the collected +information with an emphasis on different aspects of the data. Data collection +and printing are done on an "on request" basis. + +### Syntax + +Requests for real-time, on-the-fly analysis can be issued with the following +command: + +> `jcmd` *pid* `Compiler.CodeHeap_Analytics` \[*function*\] \[*granularity*\] + +If you are only interested in how the code heap looks like after running a +sample workload, you can use the command line option: + +> `-Xlog:codecache=Trace` + +To see the code heap state when a "CodeCache full" condition exists, start the +VM with the command line option: + +> `-Xlog:codecache=Debug` + +See [CodeHeap State Analytics (OpenJDK)]( +https://bugs.openjdk.org/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf) +for a detailed description of the code heap state analytics feature, the +supported functions, and the granularity options. + +## Enable Logging with the JVM Unified Logging Framework + +You use the `-Xlog` option to configure or enable logging with the Java Virtual +Machine (JVM) unified logging framework. + +### Synopsis + +> `-Xlog`\[`:`\[*what*\]\[`:`\[*output*\]\[`:`\[*decorators*\]\[`:`*output-options*\[`,`...\]\]\]\]\] +> +> `-Xlog:`*directive* + +*what* +: Specifies a combination of tags and levels of the form + *tag1*\[`+`*tag2*...\]\[`*`\]\[`=`*level*\]\[`,`...\]. Unless the wildcard + (`*`) is specified, only log messages tagged with exactly the tags + specified are matched. See [-Xlog Tags and Levels]. + +*output* +: Sets the type of output. Omitting the *output* type defaults to `stdout`. + See [-Xlog Output]. + +*decorators* +: Configures the output to use a custom set of decorators. Omitting + *decorators* defaults to `uptime`, `level`, and `tags`. See + [Decorations]. + +*output-options* +: Sets the `-Xlog` logging output options. + +*directive* +: A global option or subcommand: help, disable, async + +### Description + +The Java Virtual Machine (JVM) unified logging framework provides a common +logging system for all components of the JVM. GC logging for the JVM has been +changed to use the new logging framework. The mapping of old GC flags to the +corresponding new Xlog configuration is described in [Convert GC Logging Flags +to Xlog]. In addition, runtime logging has also been changed to use the JVM +unified logging framework. The mapping of legacy runtime logging flags to the +corresponding new Xlog configuration is described in [Convert Runtime Logging +Flags to Xlog]. + +The following provides quick reference to the `-Xlog` command and syntax for +options: + +`-Xlog` +: Enables JVM logging on an `info` level. + +`-Xlog:help` +: Prints `-Xlog` usage syntax and available tags, levels, and decorators + along with example command lines with explanations. + +`-Xlog:disable` +: Turns off all logging and clears all configuration of the logging framework + including the default configuration for warnings and errors. + +`-Xlog`\[`:`*option*\] +: Applies multiple arguments in the order that they appear on the command + line. Multiple `-Xlog` arguments for the same output override each other in + their given order. + + The *option* is set as: + + > \[*tag-selection*\]\[`:`\[*output*\]\[`:`\[*decorators*\]\[`:`*output-options*\]\]\] + + Omitting the *tag-selection* defaults to a tag-set of `all` and a level of + `info`. + + > *tag*\[`+`...\] `all` + + The `all` tag is a meta tag consisting of all tag-sets available. The + asterisk `*` in a tag set definition denotes a wildcard tag match. Matching + with a wildcard selects all tag sets that contain *at least* the specified + tags. Without the wildcard, only exact matches of the specified tag sets + are selected. + + *output-options* is + + > `filecount=`*file-count* `filesize=`*file size with optional K, M or G + suffix* `foldmultilines=`** + + When `foldmultilines` is true, a log event that consists of + multiple lines will be folded into a single line by replacing newline characters + with the sequence `'\'` and `'n'` in the output. + Existing single backslash characters will also be replaced with a sequence of + two backslashes so that the conversion can be reversed. + This option is safe to use with UTF-8 character encodings, but other encodings may not work. + For example, it may incorrectly convert multi-byte sequences in Shift JIS and BIG5. + +### Default Configuration + +When the `-Xlog` option and nothing else is specified on the command line, the +default configuration is used. The default configuration logs all messages with +a level that matches either warning or error regardless of what tags the +message is associated with. The default configuration is equivalent to entering +the following on the command line: + +> `-Xlog:all=warning:stdout:uptime,level,tags` + +### Controlling Logging at Runtime + +Logging can also be controlled at run time through Diagnostic Commands (with +the [jcmd](jcmd.html) utility). Everything that can be specified on the command line can +also be specified dynamically with the `VM.log` command. As the diagnostic +commands are automatically exposed as MBeans, you can use JMX to change logging +configuration at run time. + +### -Xlog Tags and Levels + +Each log message has a level and a tag set associated with it. The level of +the message corresponds to its details, and the tag set corresponds to what +the message contains or which JVM component it involves (such as, `gc`, +`jit`, or `os`). Mapping GC flags to the Xlog configuration is described +in [Convert GC Logging Flags to Xlog]. Mapping legacy runtime logging flags to +the corresponding Xlog configuration is described in [Convert Runtime Logging +Flags to Xlog]. + +**Available log levels:** + +- `off` +- `trace` +- `debug` +- `info` +- `warning` +- `error` + +**Available log tags:** + +There are literally dozens of log tags, which in the right combinations, will enable +a range of logging output. The full set of available log tags can be seen using `-Xlog:help`. +Specifying `all` instead of a tag combination matches all tag combinations. + +### -Xlog Output + +The `-Xlog` option supports the following types of outputs: + +- `stdout` --- Sends output to stdout +- `stderr` --- Sends output to stderr +- `file=`*filename* --- Sends output to text file(s). + +When using `file=`*filename*, specifying `%p`, `%t` and/or `%hn` in the file name +expands to the JVM's PID, startup timestamp and host name, respectively. You can also +configure text files to handle file rotation based on file size and a number of +files to rotate. For example, to rotate the log file every 10 MB and keep 5 +files in rotation, specify the options `filesize=10M, filecount=5`. The target +size of the files isn't guaranteed to be exact, it's just an approximate value. +Files are rotated by default with up to 5 rotated files of target size 20 MB, +unless configured otherwise. Specifying `filecount=0` means that the log file +shouldn't be rotated. There's a possibility of the pre-existing log file +getting overwritten. + +### -Xlog Output Mode + +By default logging messages are output synchronously - each log message is written to +the designated output when the logging call is made. But you can instead use asynchronous +logging mode by specifying: + +`-Xlog:async` +: Write all logging asynchronously. + +In asynchronous logging mode, log sites enqueue all logging messages to an intermediate buffer +and a standalone thread is responsible for flushing them to the corresponding outputs. The +intermediate buffer is bounded and on buffer exhaustion the enqueuing message is discarded. +Log entry write operations are guaranteed non-blocking. + +The option `-XX:AsyncLogBufferSize=N` specifies the memory budget in bytes for the intermediate buffer. +The default value should be big enough to cater for most cases. Users can provide a custom value to +trade memory overhead for log accuracy if they need to. + +### Decorations + +Logging messages are decorated with information about the message. You can +configure each output to use a custom set of decorators. The order of the +output is always the same as listed in the table. You can configure the +decorations to be used at run time. Decorations are prepended to the log +message. For example: + +``` +[6.567s][info][gc,old] Old collection complete +``` + +Omitting `decorators` defaults to `uptime`, `level`, and `tags`. The `none` +decorator is special and is used to turn off all decorations. + +`time` (`t`), `utctime` (`utc`), `uptime` (`u`), `timemillis` (`tm`), +`uptimemillis` (`um`), `timenanos` (`tn`), `uptimenanos` (`un`), `hostname` +(`hn`), `pid` (`p`), `tid` (`ti`), `level` (`l`), `tags` (`tg`) decorators can +also be specified as `none` for no decoration. + +Table: Logging Messages Decorations + +--------------- -------------------------------------------------------------- +Decorations Description +--------------- -------------------------------------------------------------- +`time` or `t` Current time and date in ISO-8601 format. + +`utctime` Universal Time Coordinated or Coordinated Universal Time. +or `utc` + +`uptime` or `u` Time since the start of the JVM in seconds and milliseconds. + For example, 6.567s. + +`timemillis` The same value as generated by `System.currentTimeMillis()` +or `tm` + +`uptimemillis` Milliseconds since the JVM started. +or `um` + +`timenanos` The same value generated by `System.nanoTime()`. +or `tn` + +`uptimenanos` Nanoseconds since the JVM started. +or `un` + +`hostname` The host name. +or `hn` + +`pid` or `p` The process identifier. + +`tid` or `ti` The thread identifier. + +`level` or `l` The level associated with the log message. + +`tags` or `tg` The tag-set associated with the log message. +--------------- -------------------------------------------------------------- + +### Convert GC Logging Flags to Xlog + +Table: Legacy GC Logging Flags to Xlog Configuration Mapping + +------------------------------------ -------------------------- ---------------------------------------------------- +Legacy Garbage Collection (GC) Flag Xlog Configuration Comment +------------------------------------ -------------------------- ---------------------------------------------------- +`G1PrintHeapRegions` `-Xlog:gc+region=trace` Not Applicable + +`GCLogFileSize` No configuration Log rotation is handled by the framework. + available + +`NumberOfGCLogFiles` Not Applicable Log rotation is handled by the framework. + +`PrintAdaptiveSizePolicy` `-Xlog:gc+ergo*=`*level* Use a *level* of `debug` for most of the information, + or a *level* of `trace` for all of what was logged + for `PrintAdaptiveSizePolicy`. + +`PrintGC` `-Xlog:gc` Not Applicable + +`PrintGCApplicationConcurrentTime` `-Xlog:safepoint` Note that `PrintGCApplicationConcurrentTime` and + `PrintGCApplicationStoppedTime` are logged on the + same tag and aren't separated in the new logging. + +`PrintGCApplicationStoppedTime` `-Xlog:safepoint` Note that `PrintGCApplicationConcurrentTime` and + `PrintGCApplicationStoppedTime` are logged on the + same tag and not separated in the new logging. + +`PrintGCCause` Not Applicable GC cause is now always logged. + +`PrintGCDateStamps` Not Applicable Date stamps are logged by the framework. + +`PrintGCDetails` `-Xlog:gc*` Not Applicable + +`PrintGCID` Not Applicable GC ID is now always logged. + +`PrintGCTaskTimeStamps` `-Xlog:gc+task*=debug` Not Applicable + +`PrintGCTimeStamps` Not Applicable Time stamps are logged by the framework. + +`PrintHeapAtGC` `-Xlog:gc+heap=trace` Not Applicable + +`PrintReferenceGC` `-Xlog:gc+ref*=debug` Note that in the old logging, `PrintReferenceGC` had + an effect only if `PrintGCDetails` was also enabled. + +`PrintStringDeduplicationStatistics` `-Xlog:gc+stringdedup*=debug` Not Applicable + +`PrintTenuringDistribution` `-Xlog:gc+age*=`*level* Use a *level* of `debug` for the most relevant + information, or a *level* of `trace` for all of what + was logged for `PrintTenuringDistribution`. + +`UseGCLogFileRotation` Not Applicable What was logged for `PrintTenuringDistribution`. +------------------------------------ -------------------------- ---------------------------------------------------- + +### Convert Runtime Logging Flags to Xlog + +These legacy flags are no longer recognized and will cause an error if used directly. Use their unified logging equivalent +instead. + +Table: Runtime Logging Flags to Xlog Configuration Mapping + +--------------------------- ------------------------------------- ------------------------------------------------------------------ +Legacy Runtime Flag Xlog Configuration Comment +--------------------------- ------------------------------------- ------------------------------------------------------------------ +`TraceExceptions` `-Xlog:exceptions=info` Not Applicable + +`TraceClassLoading` `-Xlog:class+load=`*level* Use *level*=`info` for regular information, or *level*=`debug` + for additional information. In Unified Logging syntax, + `-verbose:class` equals `-Xlog:class+load=info,class+unload=info`. + +`TraceClassLoadingPreorder` `-Xlog:class+preorder=debug` Not Applicable + +`TraceClassUnloading` `-Xlog:class+unload=`*level* Use *level*=`info` for regular information, or *level*=`trace` + for additional information. In Unified Logging syntax, + `-verbose:class` equals `-Xlog:class+load=info,class+unload=info`. + +`VerboseVerification` `-Xlog:verification=info` Not Applicable + +`TraceClassPaths` `-Xlog:class+path=info` Not Applicable + +`TraceClassResolution` `-Xlog:class+resolve=debug` Not Applicable + +`TraceClassInitialization` `-Xlog:class+init=info` Not Applicable + +`TraceLoaderConstraints` `-Xlog:class+loader+constraints=info` Not Applicable + + +`TraceClassLoaderData` `-Xlog:class+loader+data=`*level* Use *level*=`debug` for regular information or *level*=`trace` for + additional information. + +`TraceSafepointCleanupTime` `-Xlog:safepoint+cleanup=info` Not Applicable + +`TraceSafepoint` `-Xlog:safepoint=debug` Not Applicable + +`TraceMonitorInflation` `-Xlog:monitorinflation=debug` Not Applicable + +`TraceRedefineClasses` `-Xlog:redefine+class*=`*level* *level*=`info`, `debug`, and `trace` provide increasing amounts + of information. +--------------------------- ------------------------------------- ------------------------------------------------------------------ + +### -Xlog Usage Examples + +The following are `-Xlog` examples. + +`-Xlog` +: Logs all messages by using the `info` level to `stdout` with `uptime`, + `levels`, and `tags` decorations. This is equivalent to using: + + > `-Xlog:all=info:stdout:uptime,levels,tags` + +`-Xlog:gc` +: Logs messages tagged with the `gc` tag using `info` level to `stdout`. The + default configuration for all other messages at level `warning` is in + effect. + +`-Xlog:gc,safepoint` +: Logs messages tagged either with the `gc` or `safepoint` tags, both using + the `info` level, to `stdout`, with default decorations. Messages tagged + with both `gc` and `safepoint` won't be logged. + +`-Xlog:gc+ref=debug` +: Logs messages tagged with both `gc` and `ref` tags, using the `debug` level + to `stdout`, with default decorations. Messages tagged only with one of the + two tags won't be logged. + +`-Xlog:gc=debug:file=gc.txt:none` +: Logs messages tagged with the `gc` tag using the `debug` level to a file + called `gc.txt` with no decorations. The default configuration for all + other messages at level `warning` is still in effect. + +`-Xlog:gc=trace:file=gctrace.txt:uptimemillis,pid:filecount=5,filesize=1024` +: Logs messages tagged with the `gc` tag using the `trace` level to a + rotating file set with 5 files with size 1 MB with the base name + `gctrace.txt` and uses decorations `uptimemillis` and `pid`. + + The default configuration for all other messages at level `warning` is + still in effect. + +`-Xlog:gc::uptime,tid` +: Logs messages tagged with the `gc` tag using the default 'info' level to + default the output `stdout` and uses decorations `uptime` and `tid`. The + default configuration for all other messages at level `warning` is still in + effect. + +`-Xlog:gc*=info,safepoint*=off` +: Logs messages tagged with at least `gc` using the `info` level, but turns + off logging of messages tagged with `safepoint`. Messages tagged with both + `gc` and `safepoint` won't be logged. + +`-Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt` +: Turns off all logging, including warnings and errors, and then enables + messages tagged with `safepoint`using `trace`level to the file + `safepointtrace.txt`. The default configuration doesn't apply, because the + command line started with `-Xlog:disable`. + +### Complex -Xlog Usage Examples + +The following describes a few complex examples of using the `-Xlog` option. + +`-Xlog:gc+class*=debug` +: Logs messages tagged with at least `gc` and `class` tags using the `debug` + level to `stdout`. The default configuration for all other messages at the + level `warning` is still in effect + +`-Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt` +: Logs messages tagged with at least the `gc` and `meta` tags using the + `trace` level to the file `metatrace.txt` but turns off all messages tagged + with `class`. Messages tagged with `gc`, `meta`, and `class` aren't be + logged as `class*` is set to off. The default configuration for all other + messages at level `warning` is in effect except for those that include + `class`. + +`-Xlog:gc+meta=trace` +: Logs messages tagged with exactly the `gc` and `meta` tags using the + `trace` level to `stdout`. The default configuration for all other messages + at level `warning` is still be in effect. + +`-Xlog:gc+class+heap*=debug,meta*=warning,threads*=off` +: Logs messages tagged with at least `gc`, `class`, and `heap` tags using the + `trace` level to `stdout` but only log messages tagged with `meta` with + level. The default configuration for all other messages at the level + `warning` is in effect except for those that include `threads`. + +## Validate Java Virtual Machine Flag Arguments + +You use values provided to all Java Virtual Machine (JVM) command-line flags +for validation and, if the input value is invalid or out-of-range, then an +appropriate error message is displayed. + +Whether they're set ergonomically, in a command line, by an input tool, or +through the APIs (for example, classes contained in the package +`java.lang.management`) the values provided to all Java Virtual Machine (JVM) +command-line flags are validated. Ergonomics are described in Java Platform, +Standard Edition HotSpot Virtual Machine Garbage Collection Tuning Guide. + +Range and constraints are validated either when all flags have their values set +during JVM initialization or a flag's value is changed during runtime (for +example using the `jcmd` tool). The JVM is terminated if a value violates +either the range or constraint check and an appropriate error message is +printed on the error stream. + +For example, if a flag violates a range or a constraint check, then the JVM +exits with an error: + +``` +java -XX:AllocatePrefetchStyle=5 -version +intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ] +Improperly specified VM option 'AllocatePrefetchStyle=5' +Error: Could not create the Java Virtual Machine. +Error: A fatal exception has occurred. Program will exit. +``` + +The flag `-XX:+PrintFlagsRanges` prints the range of all the flags. This flag +allows automatic testing of the flags by the values provided by the ranges. For +the flags that have the ranges specified, the type, name, and the actual range +is printed in the output. + +For example, + +``` +intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product} +``` + +For the flags that don't have the range specified, the values aren't displayed +in the print out. For example: + +``` +size_t NewSize [ ... ] {product} +``` + +This helps to identify the flags that need to be implemented. The automatic +testing framework can skip those flags that don't have values and aren't +implemented. + +## Large Pages + +You use large pages, also known as huge pages, as memory pages that are +significantly larger than the standard memory page size (which varies depending +on the processor and operating system). Large pages optimize processor +Translation-Lookaside Buffers. + +A Translation-Lookaside Buffer (TLB) is a page translation cache that holds the +most-recently used virtual-to-physical address translations. A TLB is a scarce +system resource. A TLB miss can be costly because the processor must then read +from the hierarchical page table, which may require multiple memory accesses. +By using a larger memory page size, a single TLB entry can represent a larger +memory range. This results in less pressure on a TLB, and memory-intensive +applications may have better performance. + +However, using large pages can negatively affect system performance. For +example, when a large amount of memory is pinned by an application, it may +create a shortage of regular memory and cause excessive paging in other +applications and slow down the entire system. Also, a system that has been up +for a long time could produce excessive fragmentation, which could make it +impossible to reserve enough large page memory. When this happens, either the +OS or JVM reverts to using regular pages. + +Linux and Windows support large pages. + +### Large Pages Support for Linux + +Linux supports large pages since version 2.6. To check if your environment +supports large pages, try the following: + +``` +# cat /proc/meminfo | grep Huge +HugePages_Total: 0 +HugePages_Free: 0 +... +Hugepagesize: 2048 kB +``` + +If the output contains items prefixed with "Huge", then your system supports +large pages. The values may vary depending on environment. The `Hugepagesize` +field shows the default large page size in your environment, and the other +fields show details for large pages of this size. Newer kernels have support +for multiple large page sizes. To list the supported page sizes, run this: + +``` +# ls /sys/kernel/mm/hugepages/ +hugepages-1048576kB hugepages-2048kB +``` + +The above environment supports 2 MB and 1 GB large pages, but they need to be +configured so that the JVM can use them. When using large pages and not +enabling transparent huge pages (option `-XX:+UseTransparentHugePages`), the +number of large pages must be pre-allocated. For example, to enable 8 GB of +memory to be backed by 2 MB large pages, login as `root` and run: + +> `# echo 4096 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages` + +It is always recommended to check the value of `nr_hugepages` after the request +to make sure the kernel was able to allocate the requested number of large +pages. + +> **Note:** The values contained in `/proc` and `/sys` reset after you + reboot your system, so may want to set them in an initialization script + (for example, `rc.local` or `sysctl.conf`). + +If you configure the OS kernel parameters to enable use of large pages, the +Java processes may allocate large pages for the Java heap as well as other +internal areas, for example: + +* Code cache +* Marking bitmaps + +Consequently, if you configure the `nr_hugepages` parameter to the size of the +Java heap, then the JVM can still fail to allocate the heap using large pages +because other areas such as the code cache might already have used some of the +configured large pages. + +### Large Pages Support for Windows + +To use large pages support on Windows, the +administrator must first assign additional privileges to the user who is running +the application: + +1. Select **Control Panel**, **Administrative Tools**, and then **Local + Security Policy**. +2. Select **Local Policies** and then **User Rights Assignment**. +3. Double-click **Lock pages in memory**, then add users and/or groups. +4. Reboot your system. + +Note that these steps are required even if it's the administrator who's running +the application, because administrators by default don't have the privilege to +lock pages in memory. + +## Application Class Data Sharing + +Application Class Data Sharing (AppCDS) stores classes used +by your applications in an archive file. Since these classes are +stored in a format that can be loaded very quickly (compared +to classes stored in a JAR file), AppCDS can improve the start-up +time of your applications. In addition, AppCDS can reduce the runtime +memory footprint by sharing parts of these classes across multiple +processes. + +Classes in the CDS archive are stored in an optimized format that's +about 2 to 5 times larger than classes stored in JAR files or the JDK +runtime image. Therefore, it's a good idea to archive only those +classes that are actually used by your application. These usually +are just a small portion of all available classes. For example, your +application may use only a few APIs provided by a large library. + +### Using CDS Archives + +By default, in most JDK distributions, unless `-Xshare:off` is +specified, the JVM starts up with a default CDS archive, which +is usually located in `JAVA_HOME/lib/server/classes.jsa` (or +`JAVA_HOME\bin\server\classes.jsa` on Windows). This +archive contains about 1300 core library classes that are used +by most applications. + +To use CDS for the exact set of classes used by your application, +you can use the `-XX:SharedArchiveFile` option, which has the +general form: + +> `-XX:SharedArchiveFile=:` + +- The `` overrides the default CDS archive. +- The `` provides additional classes that can + be loaded on top of those in the ``. +- On Windows, the above path delimiter `:` should be replaced with `;` + +(The names "static" and "dynamic" are used for historical reasons. +The only significance is that the "static" archive is loaded first and +the "dynamic" archive is loaded second). + +The JVM can use up to two archives. To use only a single ``, +you can omit the `` portion: + +> `-XX:SharedArchiveFile=` + +For convenience, the `` records the location of the +``. Therefore, you can omit the `` by saying only: + +> `-XX:SharedArchiveFile=` + +### Manually Creating CDS Archives + +CDS archives can be created manually using several methods: + +- `-Xshare:dump` +- `-XX:ArchiveClassesAtExit` +- `jcmd VM.cds` + +One common operation in all these methods is a "trial run", where you run +the application once to determine the classes that should be stored +in the archive. + +#### Creating a Static CDS Archive File with -Xshare:dump + +The following steps create a static CDS archive file that contains all the classes +used by the `test.Hello` application. + +1. Create a list of all classes used by the `test.Hello` application. The + following command creates a file named `hello.classlist` that contains a + list of all classes used by this application: + + > `java -Xshare:off -XX:DumpLoadedClassList=hello.classlist -cp hello.jar test.Hello` + + The classpath specified by the `-cp` parameter must contain only + JAR files. + +2. Create a static archive, named `hello.jsa`, that contains all the classes + in `hello.classlist`: + + > `java -Xshare:dump -XX:SharedArchiveFile=hello.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar` + +3. Run the application `test.Hello` with the archive `hello.jsa`: + + > `java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hello` + +4. **Optional** Verify that the `test.Hello` application is using the class + contained in the `hello.jsa` shared archive: + + > `java -XX:SharedArchiveFile=hello.jsa -cp hello.jar -Xlog:class+load test.Hello` + + The output of this command should contain the following text: + + > `[info][class,load] test.Hello source: shared objects file` + +By default, when the `-Xshare:dump` option is used, the JVM runs in interpreter-only mode +(as if the `-Xint` option were specified). This is required for generating deterministic output +in the shared archive file. I.e., the exact same archive will be generated, bit-for-bit, every time +you dump it. However, if deterministic output is not needed, and you have a large classlist, you can +explicitly add `-Xmixed` to the command-line to enable the JIT compiler. This will speed up +the archive creation. + +#### Creating a Dynamic CDS Archive File with -XX:ArchiveClassesAtExit + +Advantages of dynamic CDS archives are: + +- They usually use less disk space, since they don't need to store the + classes that are already in the static archive. +- They are created with one fewer step than the comparable static archive. + +The following steps create a dynamic CDS archive file that contains the classes +that are used by the `test.Hello` application, excluding those that are already in +the default CDS archive. + +1. Create a dynamic CDS archive, named `hello.jsa`, that contains all the classes + in `hello.jar` loaded by the application `test.Hello`: + + > `java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello` + +2. Run the application `test.Hello` with the shared archive `hello.jsa`: + + > `java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hello` + +3. **Optional** Repeat step 4 of the previous section to verify that the `test.Hello` application is using the class + contained in the `hello.jsa` shared archive. + +It's also possible to create a dynamic CDS archive with a non-default static CDS archive. E.g., + +> `java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello` + +To run the application using this dynamic CDS archive: + +> `java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hello` + +(On Windows, the above path delimiter `:` should be replaced with `;`) + +As mention above, the name of the static archive can be skipped: + +> `java -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello` + +#### Creating CDS Archive Files with jcmd + +The previous two sections require you to modify the application's start-up script +in order to create a CDS archive. Sometimes this could be difficult, for example, +if the application's class path is set up by complex routines. + +The `jcmd VM.cds` command provides a less intrusive way for creating a CDS +archive by connecting to a running JVM process. You can create either a +static: + +> `jcmd VM.cds static_dump my_static_archive.jsa` + +or a dynamic archive: + +> `jcmd VM.cds dynamic_dump my_dynamic_archive.jsa` + +To use the resulting archive file in a subsequent run of the application +without modifying the application's start-up script, you can use the +following technique: + +> `env JAVA_TOOL_OPTIONS=-XX:SharedArchiveFile=my_static_archive.jsa bash app_start.sh` + +Note: to use `jcmd VM.cds dynamic_dump`, the JVM process identified by `` +must be started with `-XX:+RecordDynamicDumpInfo`, which can also be passed to the +application start-up script with the same technique: + +> `env JAVA_TOOL_OPTIONS=-XX:+RecordDynamicDumpInfo bash app_start.sh` + + +### Creating Dynamic CDS Archive File with -XX:+AutoCreateSharedArchive + +`-XX:+AutoCreateSharedArchive` is a more convenient way of creating/using +CDS archives. Unlike the methods of manual CDS archive creation described +in the previous section, with `-XX:+AutoCreateSharedArchive`, it's no longer +necessary to have a separate trial run. Instead, you can always run the +application with the same command-line and enjoy the benefits of CDS automatically. + +> `java -XX:+AutoCreateSharedArchive -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello` + +If the specified archive file exists and was created by the same version of the JDK, +then it will be loaded as a dynamic archive; otherwise it is ignored at VM startup. + +At VM exit, if the specified archive file does not exist, it will be created. +If it exists but was created with a different (but post JDK 19) version of the JDK, +then it will be replaced. In both cases the archive will be ready to be loaded the +next time the JVM is launched with the same command line. + +If the specified archive file exists but was created by a JDK version prior +to JDK 19, then it will be ignored: neither loaded at startup, nor replaced at exit. + +Developers should note that the contents of the CDS archive file are specific +to each build of the JDK. Therefore, if you switch to a different JDK build, +`-XX:+AutoCreateSharedArchive` will automatically recreate the archive to +match the JDK. If you intend to use this feature with an existing +archive, you should make sure that the archive is created by at least version +19 of the JDK. + + +### Restrictions on Class Path and Module Path + +- Neither the class path (`-classpath` and `-Xbootclasspath/a`) + nor the module path (`--module-path`) can contain non-empty directories. + +- Only modular JAR files are supported in `--module-path`. Exploded + modules are not supported. + +- The class path used at archive creation time must be the same as + (or a prefix of) the class path used at run time. (There's no + such requirement for the module path.) + +- The CDS archive cannot be loaded if any JAR files in the class path or + module path are modified after the archive is generated. + +- If any of the VM options `--upgrade-module-path`, `--patch-module` or + `--limit-modules` are specified, CDS is disabled. This means that the + JVM will execute without loading any CDS archives. In addition, if + you try to create a CDS archive with any of these 3 options specified, + the JVM will report an error. + +## Performance Tuning Examples + +You can use the Java advanced runtime options to optimize the performance of +your applications. + +### Tuning for Higher Throughput + +Use the following commands and advanced options to achieve higher +throughput performance for your application: + +> `java -server -XX:+UseParallelGC -XX:+UseLargePages -Xmn10g -Xms26g -Xmx26g` + +### Tuning for Lower Response Time + +Use the following commands and advanced options to achieve lower +response times for your application: + +> `java -XX:+UseG1GC -XX:MaxGCPauseMillis=100` + +### Keeping the Java Heap Small and Reducing the Dynamic Footprint of Embedded Applications + +Use the following advanced runtime options to keep the Java heap small and +reduce the dynamic footprint of embedded applications: + +> `-XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5` + +> **Note:** The defaults for these two options are 70% and 40% respectively. Because +performance sacrifices can occur when using these small settings, you should +optimize for a small footprint by reducing these settings as much as possible +without introducing unacceptable performance degradation. + +## Exit Status + +The following exit values are typically returned by the launcher when the +launcher is called with the wrong arguments, serious errors, or exceptions +thrown by the JVM. However, a Java application may choose to return any value +by using the API call `System.exit(exitValue)`. The values are: + +- `0`: Successful completion + +- `>0`: An error occurred diff --git a/src/java.base/share/man/keytool.1 b/src/java.base/share/man/keytool.1 deleted file mode 100644 index 63a134eb932..00000000000 --- a/src/java.base/share/man/keytool.1 +++ /dev/null @@ -1,2991 +0,0 @@ -.\" Copyright (c) 1998, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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. -.\" -'\" t -.\" Automatically generated by Pandoc 2.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "KEYTOOL" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -keytool - a key and certificate management utility -.SH SYNOPSIS -.PP -\f[V]keytool\f[R] [\f[I]commands\f[R]] -.TP -\f[I]commands\f[R] -Commands for \f[V]keytool\f[R] include the following: -.RS -.IP \[bu] 2 -\f[V]-certreq\f[R]: Generates a certificate request -.IP \[bu] 2 -\f[V]-changealias\f[R]: Changes an entry\[aq]s alias -.IP \[bu] 2 -\f[V]-delete\f[R]: Deletes an entry -.IP \[bu] 2 -\f[V]-exportcert\f[R]: Exports certificate -.IP \[bu] 2 -\f[V]-genkeypair\f[R]: Generates a key pair -.IP \[bu] 2 -\f[V]-genseckey\f[R]: Generates a secret key -.IP \[bu] 2 -\f[V]-gencert\f[R]: Generates a certificate from a certificate request -.IP \[bu] 2 -\f[V]-importcert\f[R]: Imports a certificate or a certificate chain -.IP \[bu] 2 -\f[V]-importpass\f[R]: Imports a password -.IP \[bu] 2 -\f[V]-importkeystore\f[R]: Imports one or all entries from another -keystore -.IP \[bu] 2 -\f[V]-keypasswd\f[R]: Changes the key password of an entry -.IP \[bu] 2 -\f[V]-list\f[R]: Lists entries in a keystore -.IP \[bu] 2 -\f[V]-printcert\f[R]: Prints the content of a certificate -.IP \[bu] 2 -\f[V]-printcertreq\f[R]: Prints the content of a certificate request -.IP \[bu] 2 -\f[V]-printcrl\f[R]: Prints the content of a Certificate Revocation List -(CRL) file -.IP \[bu] 2 -\f[V]-storepasswd\f[R]: Changes the store password of a keystore -.IP \[bu] 2 -\f[V]-showinfo\f[R]: Displays security-related information -.IP \[bu] 2 -\f[V]-version\f[R]: Prints the program version -.PP -See \f[B]Commands and Options\f[R] for a description of these commands -with their options. -.RE -.SH DESCRIPTION -.PP -The \f[V]keytool\f[R] command is a key and certificate management -utility. -It enables users to administer their own public/private key pairs and -associated certificates for use in self-authentication (where a user -authenticates themselves to other users and services) or data integrity -and authentication services, by using digital signatures. -The \f[V]keytool\f[R] command also enables users to cache the public -keys (in the form of certificates) of their communicating peers. -.PP -A certificate is a digitally signed statement from one entity (person, -company, and so on), which says that the public key (and some other -information) of some other entity has a particular value. -When data is digitally signed, the signature can be verified to check -the data integrity and authenticity. -Integrity means that the data hasn\[aq]t been modified or tampered with, -and authenticity means that the data comes from the individual who -claims to have created and signed it. -.PP -The \f[V]keytool\f[R] command also enables users to administer secret -keys and passphrases used in symmetric encryption and decryption (Data -Encryption Standard). -It can also display other security-related information. -.PP -The \f[V]keytool\f[R] command stores the keys and certificates in a -keystore. -.PP -The \f[V]keytool\f[R] command uses the -\f[V]jdk.certpath.disabledAlgorithms\f[R] and -\f[V]jdk.security.legacyAlgorithms\f[R] security properties to determine -which algorithms are considered a security risk. -It emits warnings when disabled or legacy algorithms are being used. -The \f[V]jdk.certpath.disabledAlgorithms\f[R] and -\f[V]jdk.security.legacyAlgorithms\f[R] security properties are defined -in the \f[V]java.security\f[R] file (located in the JDK\[aq]s -\f[V]$JAVA_HOME/conf/security\f[R] directory). -.SH COMMAND AND OPTION NOTES -.PP -The following notes apply to the descriptions in \f[B]Commands and -Options\f[R]: -.IP \[bu] 2 -All command and option names are preceded by a hyphen sign -(\f[V]-\f[R]). -.IP \[bu] 2 -Only one command can be provided. -.IP \[bu] 2 -Options for each command can be provided in any order. -.IP \[bu] 2 -There are two kinds of options, one is single-valued which should be -only provided once. -If a single-valued option is provided multiple times, the value of the -last one is used. -The other type is multi-valued, which can be provided multiple times and -all values are used. -The only multi-valued option currently supported is the \f[V]-ext\f[R] -option used to generate X.509v3 certificate extensions. -.IP \[bu] 2 -All items not italicized or in braces ({ }) or brackets ([ ]) are -required to appear as is. -.IP \[bu] 2 -Braces surrounding an option signify that a default value is used when -the option isn\[aq]t specified on the command line. -Braces are also used around the \f[V]-v\f[R], \f[V]-rfc\f[R], and -\f[V]-J\f[R] options, which have meaning only when they appear on the -command line. -They don\[aq]t have any default values. -.IP \[bu] 2 -Brackets surrounding an option signify that the user is prompted for the -values when the option isn\[aq]t specified on the command line. -For the \f[V]-keypass\f[R] option, if you don\[aq]t specify the option -on the command line, then the \f[V]keytool\f[R] command first attempts -to use the keystore password to recover the private/secret key. -If this attempt fails, then the \f[V]keytool\f[R] command prompts you -for the private/secret key password. -.IP \[bu] 2 -Items in italics (option values) represent the actual values that must -be supplied. -For example, here is the format of the \f[V]-printcert\f[R] command: -.RS 2 -.RS -.PP -\f[V]keytool -printcert\f[R] {\f[V]-file\f[R] \f[I]cert_file\f[R]} -{\f[V]-v\f[R]} -.RE -.PP -When you specify a \f[V]-printcert\f[R] command, replace -\f[I]cert_file\f[R] with the actual file name, as follows: -\f[V]keytool -printcert -file VScert.cer\f[R] -.RE -.IP \[bu] 2 -Option values must be enclosed in quotation marks when they contain a -blank (space). -.SH COMMANDS AND OPTIONS -.PP -The keytool commands and their options can be grouped by the tasks that -they perform. -.PP -\f[B]Commands for Creating or Adding Data to the Keystore\f[R]: -.IP \[bu] 2 -\f[V]-gencert\f[R] -.IP \[bu] 2 -\f[V]-genkeypair\f[R] -.IP \[bu] 2 -\f[V]-genseckey\f[R] -.IP \[bu] 2 -\f[V]-importcert\f[R] -.IP \[bu] 2 -\f[V]-importpass\f[R] -.PP -\f[B]Commands for Importing Contents from Another Keystore\f[R]: -.IP \[bu] 2 -\f[V]-importkeystore\f[R] -.PP -\f[B]Commands for Generating a Certificate Request\f[R]: -.IP \[bu] 2 -\f[V]-certreq\f[R] -.PP -\f[B]Commands for Exporting Data\f[R]: -.IP \[bu] 2 -\f[V]-exportcert\f[R] -.PP -\f[B]Commands for Displaying Data\f[R]: -.IP \[bu] 2 -\f[V]-list\f[R] -.IP \[bu] 2 -\f[V]-printcert\f[R] -.IP \[bu] 2 -\f[V]-printcertreq\f[R] -.IP \[bu] 2 -\f[V]-printcrl\f[R] -.PP -\f[B]Commands for Managing the Keystore\f[R]: -.IP \[bu] 2 -\f[V]-storepasswd\f[R] -.IP \[bu] 2 -\f[V]-keypasswd\f[R] -.IP \[bu] 2 -\f[V]-delete\f[R] -.IP \[bu] 2 -\f[V]-changealias\f[R] -.PP -\f[B]Commands for Displaying Security-related Information\f[R]: -.IP \[bu] 2 -\f[V]-showinfo\f[R] -.PP -\f[B]Commands for Displaying Program Version\f[R]: -.IP \[bu] 2 -\f[V]-version\f[R] -.SH COMMANDS FOR CREATING OR ADDING DATA TO THE KEYSTORE -.TP -\f[V]-gencert\f[R] -The following are the available options for the \f[V]-gencert\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-rfc\f[R]}: Output in RFC (Request For Comment) style -.IP \[bu] 2 -{\f[V]-infile\f[R] \f[I]infile\f[R]}: Input file name -.IP \[bu] 2 -{\f[V]-outfile\f[R] \f[I]outfile\f[R]}: Output file name -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-sigalg\f[R] \f[I]sigalg\f[R]}: Signature algorithm name -.IP \[bu] 2 -{\f[V]-dname\f[R] \f[I]dname\f[R]}: Distinguished name -.IP \[bu] 2 -{\f[V]-startdate\f[R] \f[I]startdate\f[R]}: Certificate validity start -date and time -.IP \[bu] 2 -{\f[V]-ext\f[R] \f[I]ext\f[R]}*: X.509 extension -.IP \[bu] 2 -{\f[V]-validity\f[R] \f[I]days\f[R]}: Validity number of days -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Adds a security provider by name (such as SunPKCS11) -with an optional configure argument. -The value of the security provider is the name of a security provider -that is defined in a module. -.RS 2 -.PP -For example, -.RS -.PP -\f[V]keytool -addprovider SunPKCS11 -providerarg some.cfg ...\f[R] -.RE -.PP -\f[B]Note:\f[R] -.PP -For compatibility reasons, the SunPKCS11 provider can still be loaded -with \f[V]-providerclass sun.security.pkcs11.SunPKCS11\f[R] even if it -is now defined in a module. -This is the only module included in the JDK that needs a configuration, -and therefore the most widely used with the \f[V]-providerclass\f[R] -option. -For legacy security providers located on classpath and loaded by -reflection, \f[V]-providerclass\f[R] should still be used. -.RE -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.RS 2 -.PP -For example, if \f[V]MyProvider\f[R] is a legacy provider loaded via -reflection, -.RS -.PP -\f[V]keytool -providerclass com.example.MyProvider ...\f[R] -.RE -.RE -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-gencert\f[R] command to generate a certificate as a -response to a certificate request file (which can be created by the -\f[V]keytool -certreq\f[R] command). -The command reads the request either from \f[I]infile\f[R] or, if -omitted, from the standard input, signs it by using the alias\[aq]s -private key, and outputs the X.509 certificate into either -\f[I]outfile\f[R] or, if omitted, to the standard output. -When \f[V]-rfc\f[R] is specified, the output format is Base64-encoded -PEM; otherwise, a binary DER is created. -.PP -The \f[V]-sigalg\f[R] value specifies the algorithm that should be used -to sign the certificate. -The \f[I]startdate\f[R] argument is the start time and date that the -certificate is valid. -The \f[I]days\f[R] argument tells the number of days for which the -certificate should be considered valid. -.PP -When \f[I]dname\f[R] is provided, it is used as the subject of the -generated certificate. -Otherwise, the one from the certificate request is used. -.PP -The \f[V]-ext\f[R] value shows what X.509 extensions will be embedded in -the certificate. -Read \f[B]Common Command Options\f[R] for the grammar of \f[V]-ext\f[R]. -.PP -The \f[V]-gencert\f[R] option enables you to create certificate chains. -The following example creates a certificate, \f[V]e1\f[R], that contains -three certificates in its certificate chain. -.PP -The following commands creates four key pairs named \f[V]ca\f[R], -\f[V]ca1\f[R], \f[V]ca2\f[R], and \f[V]e1\f[R]: -.IP -.nf -\f[CB] -keytool -alias ca -dname CN=CA -genkeypair -keyalg rsa -keytool -alias ca1 -dname CN=CA -genkeypair -keyalg rsa -keytool -alias ca2 -dname CN=CA -genkeypair -keyalg rsa -keytool -alias e1 -dname CN=E1 -genkeypair -keyalg rsa -\f[R] -.fi -.PP -The following two commands create a chain of signed certificates; -\f[V]ca\f[R] signs \f[V]ca1\f[R] and \f[V]ca1\f[R] signs \f[V]ca2\f[R], -all of which are self-issued: -.IP -.nf -\f[CB] -keytool -alias ca1 -certreq | - keytool -alias ca -gencert -ext san=dns:ca1 | - keytool -alias ca1 -importcert - -keytool -alias ca2 -certreq | - keytool -alias ca1 -gencert -ext san=dns:ca2 | - keytool -alias ca2 -importcert -\f[R] -.fi -.PP -The following command creates the certificate \f[V]e1\f[R] and stores it -in the \f[V]e1.cert\f[R] file, which is signed by \f[V]ca2\f[R]. -As a result, \f[V]e1\f[R] should contain \f[V]ca\f[R], \f[V]ca1\f[R], -and \f[V]ca2\f[R] in its certificate chain: -.RS -.PP -\f[V]keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert\f[R] -.RE -.RE -.TP -\f[V]-genkeypair\f[R] -The following are the available options for the \f[V]-genkeypair\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -\f[V]-keyalg\f[R] \f[I]alg\f[R]: Key algorithm name -.IP \[bu] 2 -{\f[V]-keysize\f[R] \f[I]size\f[R]}: Key bit size -.IP \[bu] 2 -{\f[V]-groupname\f[R] \f[I]name\f[R]}: Group name. -For example, an Elliptic Curve name. -.IP \[bu] 2 -{\f[V]-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name -.IP \[bu] 2 -{\f[V]-signer\f[R] \f[I]alias\f[R]}: Signer alias -.IP \[bu] 2 -[\f[V]-signerkeypass\f[R] \f[I]arg\f[R]]: Signer key password -.IP \[bu] 2 -[\f[V]-dname\f[R] \f[I]name\f[R]]: Distinguished name -.IP \[bu] 2 -{\f[V]-startdate\f[R] \f[I]date\f[R]}: Certificate validity start date -and time -.IP \[bu] 2 -{\f[V]-ext\f[R] \f[I]value\f[R]}*: X.509 extension -.IP \[bu] 2 -{\f[V]-validity\f[R] \f[I]days\f[R]}: Validity number of days -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]] }: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-genkeypair\f[R] command to generate a key pair (a public -key and associated private key). -When the \f[V]-signer\f[R] option is not specified, the public key is -wrapped in an X.509 v3 self-signed certificate and stored as a -single-element certificate chain. -When the \f[V]-signer\f[R] option is specified, a new certificate is -generated and signed by the designated signer and stored as a -multiple-element certificate chain (containing the generated certificate -itself, and the signer\[aq]s certificate chain). -The certificate chain and private key are stored in a new keystore entry -that is identified by its alias. -.PP -The \f[V]-keyalg\f[R] value specifies the algorithm to be used to -generate the key pair. -The \f[V]-keysize\f[R] value specifies the size of each key to be -generated. -The \f[V]-groupname\f[R] value specifies the named group (for example, -the standard or predefined name of an Elliptic Curve) of the key to be -generated. -.PP -When a \f[V]-keysize\f[R] value is provided, it will be used to -initialize a \f[V]KeyPairGenerator\f[R] object using the -\f[V]initialize(int keysize)\f[R] method. -When a \f[V]-groupname\f[R] value is provided, it will be used to -initialize a \f[V]KeyPairGenerator\f[R] object using the -\f[V]initialize(AlgorithmParameterSpec params)\f[R] method where -\f[V]params\f[R] is \f[V]new NamedParameterSpec(groupname)\f[R]. -.PP -Only one of \f[V]-groupname\f[R] and \f[V]-keysize\f[R] can be -specified. -If an algorithm has multiple named groups that have the same key size, -the \f[V]-groupname\f[R] option should usually be used. -In this case, if \f[V]-keysize\f[R] is specified, it\[aq]s up to the -security provider to determine which named group is chosen when -generating a key pair. -.PP -The \f[V]-sigalg\f[R] value specifies the algorithm that should be used -to sign the certificate. -This algorithm must be compatible with the \f[V]-keyalg\f[R] value. -.PP -The \f[V]-signer\f[R] value specifies the alias of a -\f[V]PrivateKeyEntry\f[R] for the signer that already exists in the -keystore. -This option is used to sign the certificate with the signer\[aq]s -private key. -This is especially useful for key agreement algorithms (i.e. -the \f[V]-keyalg\f[R] value is \f[V]XDH\f[R], \f[V]X25519\f[R], -\f[V]X448\f[R], or \f[V]DH\f[R]) as these keys cannot be used for -digital signatures, and therefore a self-signed certificate cannot be -created. -.PP -The \f[V]-signerkeypass\f[R] value specifies the password of the -signer\[aq]s private key. -It can be specified if the private key of the signer entry is protected -by a password different from the store password. -.PP -The \f[V]-dname\f[R] value specifies the X.500 Distinguished Name to be -associated with the value of \f[V]-alias\f[R]. -If the \f[V]-signer\f[R] option is not specified, the issuer and subject -fields of the self-signed certificate are populated with the specified -distinguished name. -If the \f[V]-signer\f[R] option is specified, the subject field of the -certificate is populated with the specified distinguished name and the -issuer field is populated with the subject field of the signer\[aq]s -certificate. -If a distinguished name is not provided at the command line, then the -user is prompted for one. -.PP -The value of \f[V]-keypass\f[R] is a password used to protect the -private key of the generated key pair. -If a password is not provided, then the user is prompted for it. -If you press the \f[B]Return\f[R] key at the prompt, then the key -password is set to the same password as the keystore password. -The \f[V]-keypass\f[R] value must have at least six characters. -.PP -The value of \f[V]-startdate\f[R] specifies the issue time of the -certificate, also known as the \[dq]Not Before\[dq] value of the X.509 -certificate\[aq]s Validity field. -.PP -The option value can be set in one of these two forms: -.PP -([\f[V]+-\f[R]]\f[I]nnn\f[R][\f[V]ymdHMS\f[R]])+ -.PP -[\f[I]yyyy\f[R]\f[V]/\f[R]\f[I]mm\f[R]\f[V]/\f[R]\f[I]dd\f[R]] -[\f[I]HH\f[R]\f[V]:\f[R]\f[I]MM\f[R]\f[V]:\f[R]\f[I]SS\f[R]] -.PP -With the first form, the issue time is shifted by the specified value -from the current time. -The value is a concatenation of a sequence of subvalues. -Inside each subvalue, the plus sign (+) means shift forward, and the -minus sign (-) means shift backward. -The time to be shifted is \f[I]nnn\f[R] units of years, months, days, -hours, minutes, or seconds (denoted by a single character of -\f[V]y\f[R], \f[V]m\f[R], \f[V]d\f[R], \f[V]H\f[R], \f[V]M\f[R], or -\f[V]S\f[R] respectively). -The exact value of the issue time is calculated by using the -\f[V]java.util.GregorianCalendar.add(int field, int amount)\f[R] method -on each subvalue, from left to right. -For example, the issue time can be specified by: -.IP -.nf -\f[CB] -Calendar c = new GregorianCalendar(); -c.add(Calendar.YEAR, -1); -c.add(Calendar.MONTH, 1); -c.add(Calendar.DATE, -1); -return c.getTime() -\f[R] -.fi -.PP -With the second form, the user sets the exact issue time in two parts, -year/month/day and hour:minute:second (using the local time zone). -The user can provide only one part, which means the other part is the -same as the current date (or time). -The user must provide the exact number of digits shown in the format -definition (padding with 0 when shorter). -When both date and time are provided, there is one (and only one) space -character between the two parts. -The hour should always be provided in 24-hour format. -.PP -When the option isn\[aq]t provided, the start date is the current time. -The option can only be provided one time. -.PP -The value of \f[I]date\f[R] specifies the number of days (starting at -the date specified by \f[V]-startdate\f[R], or the current date when -\f[V]-startdate\f[R] isn\[aq]t specified) for which the certificate -should be considered valid. -.RE -.TP -\f[V]-genseckey\f[R] -The following are the available options for the \f[V]-genseckey\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -\f[V]-keyalg\f[R] \f[I]alg\f[R]: Key algorithm name -.IP \[bu] 2 -{\f[V]-keysize\f[R] \f[I]size\f[R]}: Key bit size -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-genseckey\f[R] command to generate a secret key and store -it in a new \f[V]KeyStore.SecretKeyEntry\f[R] identified by -\f[V]alias\f[R]. -.PP -The value of \f[V]-keyalg\f[R] specifies the algorithm to be used to -generate the secret key, and the value of \f[V]-keysize\f[R] specifies -the size of the key that is generated. -The \f[V]-keypass\f[R] value is a password that protects the secret key. -If a password is not provided, then the user is prompted for it. -If you press the \f[B]Return\f[R] key at the prompt, then the key -password is set to the same password that is used for the -\f[V]-keystore\f[R]. -The \f[V]-keypass\f[R] value must contain at least six characters. -.RE -.TP -\f[V]-importcert\f[R] -The following are the available options for the \f[V]-importcert\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-noprompt\f[R]}: Do not prompt -.IP \[bu] 2 -{\f[V]-trustcacerts\f[R]}: Trust certificates from cacerts -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password is provided through protected mechanism -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-file\f[R] \f[I]file\f[R]}: Input file name -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-importcert\f[R] command to read the certificate or -certificate chain (where the latter is supplied in a PKCS#7 formatted -reply or in a sequence of X.509 certificates) from \f[V]-file\f[R] -\f[I]file\f[R], and store it in the \f[V]keystore\f[R] entry identified -by \f[V]-alias\f[R]. -If \f[V]-file\f[R] \f[I]file\f[R] is not specified, then the certificate -or certificate chain is read from \f[V]stdin\f[R]. -.PP -The \f[V]keytool\f[R] command can import X.509 v1, v2, and v3 -certificates, and PKCS#7 formatted certificate chains consisting of -certificates of that type. -The data to be imported must be provided either in binary encoding -format or in printable encoding format (also known as Base64 encoding) -as defined by the Internet RFC 1421 standard. -In the latter case, the encoding must be bounded at the beginning by a -string that starts with \f[V]-----BEGIN\f[R], and bounded at the end by -a string that starts with \f[V]-----END\f[R]. -.PP -You import a certificate for two reasons: To add it to the list of -trusted certificates, and to import a certificate reply received from a -certificate authority (CA) as the result of submitting a Certificate -Signing Request (CSR) to that CA. -See the \f[V]-certreq\f[R] command in \f[B]Commands for Generating a -Certificate Request\f[R]. -.PP -The type of import is indicated by the value of the \f[V]-alias\f[R] -option. -If the alias doesn\[aq]t point to a key entry, then the -\f[V]keytool\f[R] command assumes you are adding a trusted certificate -entry. -In this case, the alias shouldn\[aq]t already exist in the keystore. -If the alias does exist, then the \f[V]keytool\f[R] command outputs an -error because a trusted certificate already exists for that alias, and -doesn\[aq]t import the certificate. -If \f[V]-alias\f[R] points to a key entry, then the \f[V]keytool\f[R] -command assumes that you\[aq]re importing a certificate reply. -.RE -.TP -\f[V]-importpass\f[R] -The following are the available options for the \f[V]-importpass\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keyalg\f[R] \f[I]alg\f[R]}: Key algorithm name -.IP \[bu] 2 -{\f[V]-keysize\f[R] \f[I]size\f[R]}: Key bit size -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-importpass\f[R] command to imports a passphrase and store -it in a new \f[V]KeyStore.SecretKeyEntry\f[R] identified by -\f[V]-alias\f[R]. -The passphrase may be supplied via the standard input stream; otherwise -the user is prompted for it. -The \f[V]-keypass\f[R] option provides a password to protect the -imported passphrase. -If a password is not provided, then the user is prompted for it. -If you press the \f[B]Return\f[R] key at the prompt, then the key -password is set to the same password as that used for the -\f[V]keystore\f[R]. -The \f[V]-keypass\f[R] value must contain at least six characters. -.RE -.SH COMMANDS FOR IMPORTING CONTENTS FROM ANOTHER KEYSTORE -.TP -\f[V]-importkeystore\f[R] -The following are the available options for the -\f[V]-importkeystore\f[R] command: -.RS -.IP \[bu] 2 -\f[V]-srckeystore\f[R] \f[I]keystore\f[R]: Source keystore name -.IP \[bu] 2 -{\f[V]-destkeystore\f[R] \f[I]keystore\f[R]}: Destination keystore name -.IP \[bu] 2 -{\f[V]-srcstoretype\f[R] \f[I]type\f[R]}: Source keystore type -.IP \[bu] 2 -{\f[V]-deststoretype\f[R] \f[I]type\f[R]}: Destination keystore type -.IP \[bu] 2 -[\f[V]-srcstorepass\f[R] \f[I]arg\f[R]]: Source keystore password -.IP \[bu] 2 -[\f[V]-deststorepass\f[R] \f[I]arg\f[R]]: Destination keystore password -.IP \[bu] 2 -{\f[V]-srcprotected\f[R]}: Source keystore password protected -.IP \[bu] 2 -{\f[V]-destprotected\f[R]}: Destination keystore password protected -.IP \[bu] 2 -{\f[V]-srcprovidername\f[R] \f[I]name\f[R]}: Source keystore provider -name -.IP \[bu] 2 -{\f[V]-destprovidername\f[R] \f[I]name\f[R]}: Destination keystore -provider name -.IP \[bu] 2 -{\f[V]-srcalias\f[R] \f[I]alias\f[R]}: Source alias -.IP \[bu] 2 -{\f[V]-destalias\f[R] \f[I]alias\f[R]}: Destination alias -.IP \[bu] 2 -[\f[V]-srckeypass\f[R] \f[I]arg\f[R]]: Source key password -.IP \[bu] 2 -[\f[V]-destkeypass\f[R] \f[I]arg\f[R]]: Destination key password -.IP \[bu] 2 -{\f[V]-noprompt\f[R]}: Do not prompt -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -\f[B]Note:\f[R] -.PP -This is the first line of all options: -.RS -.PP -\f[V]-srckeystore\f[R] \f[I]keystore\f[R] \f[V]-destkeystore\f[R] -\f[I]keystore\f[R] -.RE -.PP -Use the \f[V]-importkeystore\f[R] command to import a single entry or -all entries from a source keystore to a destination keystore. -.PP -\f[B]Note:\f[R] -.PP -If you do not specify \f[V]-destkeystore\f[R] when using the -\f[V]keytool -importkeystore\f[R] command, then the default keystore -used is \f[V]$HOME/.keystore\f[R]. -.PP -When the \f[V]-srcalias\f[R] option is provided, the command imports the -single entry identified by the alias to the destination keystore. -If a destination alias isn\[aq]t provided with \f[V]-destalias\f[R], -then \f[V]-srcalias\f[R] is used as the destination alias. -If the source entry is protected by a password, then -\f[V]-srckeypass\f[R] is used to recover the entry. -If \f[V]-srckeypass\f[R] isn\[aq]t provided, then the \f[V]keytool\f[R] -command attempts to use \f[V]-srcstorepass\f[R] to recover the entry. -If \f[V]-srcstorepass\f[R] is not provided or is incorrect, then the -user is prompted for a password. -The destination entry is protected with \f[V]-destkeypass\f[R]. -If \f[V]-destkeypass\f[R] isn\[aq]t provided, then the destination entry -is protected with the source entry password. -For example, most third-party tools require \f[V]storepass\f[R] and -\f[V]keypass\f[R] in a PKCS #12 keystore to be the same. -To create a PKCS#12 keystore for these tools, always specify a -\f[V]-destkeypass\f[R] that is the same as \f[V]-deststorepass\f[R]. -.PP -If the \f[V]-srcalias\f[R] option isn\[aq]t provided, then all entries -in the source keystore are imported into the destination keystore. -Each destination entry is stored under the alias from the source entry. -If the source entry is protected by a password, then -\f[V]-srcstorepass\f[R] is used to recover the entry. -If \f[V]-srcstorepass\f[R] is not provided or is incorrect, then the -user is prompted for a password. -If a source keystore entry type isn\[aq]t supported in the destination -keystore, or if an error occurs while storing an entry into the -destination keystore, then the user is prompted either to skip the entry -and continue or to quit. -The destination entry is protected with the source entry password. -.PP -If the destination alias already exists in the destination keystore, -then the user is prompted either to overwrite the entry or to create a -new entry under a different alias name. -.PP -If the \f[V]-noprompt\f[R] option is provided, then the user isn\[aq]t -prompted for a new destination alias. -Existing entries are overwritten with the destination alias name. -Entries that can\[aq]t be imported are skipped and a warning is -displayed. -.RE -.SH COMMANDS FOR GENERATING A CERTIFICATE REQUEST -.TP -\f[V]-certreq\f[R] -The following are the available options for the \f[V]-certreq\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name -.IP \[bu] 2 -{\f[V]-file\f[R] \f[I]file\f[R]}: Output file name -.IP \[bu] 2 -[ \f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-dname\f[R] \f[I]name\f[R]}: Distinguished name -.IP \[bu] 2 -{\f[V]-ext\f[R] \f[I]value\f[R]}: X.509 extension -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-certreq\f[R] command to generate a Certificate Signing -Request (CSR) using the PKCS #10 format. -.PP -A CSR is intended to be sent to a CA. -The CA authenticates the certificate requestor (usually offline) and -returns a certificate or certificate chain to replace the existing -certificate chain (initially a self-signed certificate) in the keystore. -.PP -The private key associated with \f[I]alias\f[R] is used to create the -PKCS #10 certificate request. -To access the private key, the correct password must be provided. -If \f[V]-keypass\f[R] isn\[aq]t provided at the command line and is -different from the password used to protect the integrity of the -keystore, then the user is prompted for it. -If \f[V]-dname\f[R] is provided, then it is used as the subject in the -CSR. -Otherwise, the X.500 Distinguished Name associated with alias is used. -.PP -The \f[V]-sigalg\f[R] value specifies the algorithm that should be used -to sign the CSR. -.PP -The CSR is stored in the \f[V]-file\f[R] \f[I]file\f[R]. -If a file is not specified, then the CSR is output to \f[V]-stdout\f[R]. -.PP -Use the \f[V]-importcert\f[R] command to import the response from the -CA. -.RE -.SH COMMANDS FOR EXPORTING DATA -.TP -\f[V]-exportcert\f[R] -The following are the available options for the \f[V]-exportcert\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-rfc\f[R]}: Output in RFC style -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-file\f[R] \f[I]file\f[R]}: Output file name -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]] }: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-exportcert\f[R] command to read a certificate from the -keystore that is associated with \f[V]-alias\f[R] \f[I]alias\f[R] and -store it in the \f[V]-file\f[R] \f[I]file\f[R]. -When a file is not specified, the certificate is output to -\f[V]stdout\f[R]. -.PP -By default, the certificate is output in binary encoding. -If the \f[V]-rfc\f[R] option is specified, then the output in the -printable encoding format defined by the Internet RFC 1421 Certificate -Encoding Standard. -.PP -If \f[V]-alias\f[R] refers to a trusted certificate, then that -certificate is output. -Otherwise, \f[V]-alias\f[R] refers to a key entry with an associated -certificate chain. -In that case, the first certificate in the chain is returned. -This certificate authenticates the public key of the entity addressed by -\f[V]-alias\f[R]. -.RE -.SH COMMANDS FOR DISPLAYING DATA -.TP -\f[V]-list\f[R] -The following are the available options for the \f[V]-list\f[R] command: -.RS -.IP \[bu] 2 -{\f[V]-rfc\f[R]}: Output in RFC style -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]] }: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-list\f[R] command to print the contents of the keystore -entry identified by \f[V]-alias\f[R] to \f[V]stdout\f[R]. -If \f[V]-alias\f[R] \f[I]alias\f[R] is not specified, then the contents -of the entire keystore are printed. -.PP -By default, this command prints the SHA-256 fingerprint of a -certificate. -If the \f[V]-v\f[R] option is specified, then the certificate is printed -in human-readable format, with additional information such as the owner, -issuer, serial number, and any extensions. -If the \f[V]-rfc\f[R] option is specified, then the certificate contents -are printed by using the printable encoding format, as defined by the -Internet RFC 1421 Certificate Encoding Standard. -.PP -\f[B]Note:\f[R] -.PP -You can\[aq]t specify both \f[V]-v\f[R] and \f[V]-rfc\f[R] in the same -command. -Otherwise, an error is reported. -.RE -.TP -\f[V]-printcert\f[R] -The following are the available options for the \f[V]-printcert\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-rfc\f[R]}: Output in RFC style -.IP \[bu] 2 -{\f[V]-file\f[R] \f[I]cert_file\f[R]}: Input file name -.IP \[bu] 2 -{\f[V]-sslserver\f[R] \f[I]server\f[R][\f[V]:\f[R]\f[I]port\f[R]]}:: -Secure Sockets Layer (SSL) server host and port -.IP \[bu] 2 -{\f[V]-jarfile\f[R] \f[I]JAR_file\f[R]}: Signed \f[V].jar\f[R] file -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-trustcacerts\f[R]}: Trust certificates from cacerts -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password is provided through protected mechanism -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-printcert\f[R] command to read and print the certificate -from \f[V]-file\f[R] \f[I]cert_file\f[R], the SSL server located at -\f[V]-sslserver\f[R] \f[I]server\f[R][\f[V]:\f[R]\f[I]port\f[R]], or the -signed JAR file specified by \f[V]-jarfile\f[R] \f[I]JAR_file\f[R]. -It prints its contents in a human-readable format. -When a port is not specified, the standard HTTPS port 443 is assumed. -.PP -\f[B]Note:\f[R] -.PP -The \f[V]-sslserver\f[R] and \f[V]-file\f[R] options can\[aq]t be -provided in the same command. -Otherwise, an error is reported. -If you don\[aq]t specify either option, then the certificate is read -from \f[V]stdin\f[R]. -.PP -When\f[V]-rfc\f[R] is specified, the \f[V]keytool\f[R] command prints -the certificate in PEM mode as defined by the Internet RFC 1421 -Certificate Encoding standard. -.PP -If the certificate is read from a file or \f[V]stdin\f[R], then it might -be either binary encoded or in printable encoding format, as defined by -the RFC 1421 Certificate Encoding standard. -.PP -If the SSL server is behind a firewall, then the -\f[V]-J-Dhttps.proxyHost=proxyhost\f[R] and -\f[V]-J-Dhttps.proxyPort=proxyport\f[R] options can be specified on the -command line for proxy tunneling. -.PP -\f[B]Note:\f[R] -.PP -This command can be used independently of a keystore. -This command does not check for the weakness of a certificate\[aq]s -signature algorithm if it is a trusted certificate in the user keystore -(specified by \f[V]-keystore\f[R]) or in the \f[V]cacerts\f[R] keystore -(if \f[V]-trustcacerts\f[R] is specified). -.RE -.TP -\f[V]-printcertreq\f[R] -The following are the available options for the \f[V]-printcertreq\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-file\f[R] \f[I]file\f[R]}: Input file name -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-printcertreq\f[R] command to print the contents of a PKCS -#10 format certificate request, which can be generated by the -\f[V]keytool -certreq\f[R] command. -The command reads the request from file. -If there is no file, then the request is read from the standard input. -.RE -.TP -\f[V]-printcrl\f[R] -The following are the available options for the \f[V]-printcrl\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-file crl\f[R]}: Input file name -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-trustcacerts\f[R]}: Trust certificates from cacerts -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password is provided through protected mechanism -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-printcrl\f[R] command to read the Certificate Revocation -List (CRL) from \f[V]-file crl\f[R] . -A CRL is a list of the digital certificates that were revoked by the CA -that issued them. -The CA generates the \f[V]crl\f[R] file. -.PP -\f[B]Note:\f[R] -.PP -This command can be used independently of a keystore. -This command attempts to verify the CRL using a certificate from the -user keystore (specified by \f[V]-keystore\f[R]) or the -\f[V]cacerts\f[R] keystore (if \f[V]-trustcacerts\f[R] is specified), -and will print out a warning if it cannot be verified. -.RE -.SH COMMANDS FOR MANAGING THE KEYSTORE -.TP -\f[V]-storepasswd\f[R] -The following are the available options for the \f[V]-storepasswd\f[R] -command: -.RS -.IP \[bu] 2 -[\f[V]-new\f[R] \f[I]arg\f[R]]: New password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-storepasswd\f[R] command to change the password used to -protect the integrity of the keystore contents. -The new password is set by \f[V]-new\f[R] \f[I]arg\f[R] and must contain -at least six characters. -.RE -.TP -\f[V]-keypasswd\f[R] -The following are the available options for the \f[V]-keypasswd\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]old_keypass\f[R]]: Key password -.IP \[bu] 2 -[\f[V]-new\f[R] \f[I]new_keypass\f[R]]: New password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-storepass\f[R] \f[I]arg\f[R]}: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-keypasswd\f[R] command to change the password (under which -private/secret keys identified by \f[V]-alias\f[R] are protected) from -\f[V]-keypass\f[R] \f[I]old_keypass\f[R] to \f[V]-new\f[R] -\f[I]new_keypass\f[R]. -The password value must contain at least six characters. -.PP -If the \f[V]-keypass\f[R] option isn\[aq]t provided at the command line -and the \f[V]-keypass\f[R] password is different from the keystore -password (\f[V]-storepass\f[R] \f[I]arg\f[R]), then the user is prompted -for it. -.PP -If the \f[V]-new\f[R] option isn\[aq]t provided at the command line, -then the user is prompted for it. -.RE -.TP -\f[V]-delete\f[R] -The following are the available options for the \f[V]-delete\f[R] -command: -.RS -.IP \[bu] 2 -[\f[V]-alias\f[R] \f[I]alias\f[R]]: Alias name of the entry to process -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-delete\f[R] command to delete the \f[V]-alias\f[R] -\f[I]alias\f[R] entry from the keystore. -When not provided at the command line, the user is prompted for the -\f[V]alias\f[R]. -.RE -.TP -\f[V]-changealias\f[R] -The following are the available options for the \f[V]-changealias\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-alias\f[R] \f[I]alias\f[R]}: Alias name of the entry to process -.IP \[bu] 2 -[\f[V]-destalias\f[R] \f[I]alias\f[R]]: Destination alias -.IP \[bu] 2 -[\f[V]-keypass\f[R] \f[I]arg\f[R]]: Key password -.IP \[bu] 2 -{\f[V]-keystore\f[R] \f[I]keystore\f[R]}: Keystore name -.IP \[bu] 2 -{\f[V]-cacerts\f[R]}: Access the cacerts keystore -.IP \[bu] 2 -[\f[V]-storepass\f[R] \f[I]arg\f[R]]: Keystore password -.IP \[bu] 2 -{\f[V]-storetype\f[R] \f[I]type\f[R]}: Keystore type -.IP \[bu] 2 -{\f[V]-providername\f[R] \f[I]name\f[R]}: Provider name -.IP \[bu] 2 -{\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by name (such as SunPKCS11) with -an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerclass\f[R] \f[I]class\f[R] [\f[V]-providerarg\f[R] -\f[I]arg\f[R]]}: Add security provider by fully qualified class name -with an optional configure argument. -.IP \[bu] 2 -{\f[V]-providerpath\f[R] \f[I]list\f[R]}: Provider classpath -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.IP \[bu] 2 -{\f[V]-protected\f[R]}: Password provided through a protected mechanism -.PP -Use the \f[V]-changealias\f[R] command to move an existing keystore -entry from \f[V]-alias\f[R] \f[I]alias\f[R] to a new -\f[V]-destalias\f[R] \f[I]alias\f[R]. -If a destination alias is not provided, then the command prompts you for -one. -If the original entry is protected with an entry password, then the -password can be supplied with the \f[V]-keypass\f[R] option. -If a key password is not provided, then the \f[V]-storepass\f[R] (if -provided) is attempted first. -If the attempt fails, then the user is prompted for a password. -.RE -.SH COMMANDS FOR DISPLAYING SECURITY-RELATED INFORMATION -.TP -\f[V]-showinfo\f[R] -The following are the available options for the \f[V]-showinfo\f[R] -command: -.RS -.IP \[bu] 2 -{\f[V]-tls\f[R]}: Displays TLS configuration information -.IP \[bu] 2 -{\f[V]-v\f[R]}: Verbose output -.PP -Use the \f[V]-showinfo\f[R] command to display various security-related -information. -The \f[V]-tls\f[R] option displays TLS configurations, such as the list -of enabled protocols and cipher suites. -.RE -.SH COMMANDS FOR DISPLAYING PROGRAM VERSION -.PP -You can use \f[V]-version\f[R] to print the program version of -\f[V]keytool\f[R]. -.SH COMMANDS FOR DISPLAYING HELP INFORMATION -.PP -You can use \f[V]--help\f[R] to display a list of \f[V]keytool\f[R] -commands or to display help information about a specific -\f[V]keytool\f[R] command. -.IP \[bu] 2 -To display a list of \f[V]keytool\f[R] commands, enter: -.RS 2 -.RS -.PP -\f[V]keytool --help\f[R] -.RE -.RE -.IP \[bu] 2 -To display help information about a specific \f[V]keytool\f[R] command, -enter: -.RS 2 -.RS -.PP -\f[V]keytool - --help\f[R] -.RE -.RE -.SH COMMON COMMAND OPTIONS -.PP -The \f[V]-v\f[R] option can appear for all commands except -\f[V]--help\f[R]. -When the \f[V]-v\f[R] option appears, it signifies verbose mode, which -means that more information is provided in the output. -.PP -The \f[V]-J\f[R]\f[I]option\f[R] argument can appear for any command. -When the \f[V]-J\f[R]\f[I]option\f[R] is used, the specified -\f[I]option\f[R] string is passed directly to the Java interpreter. -This option doesn\[aq]t contain any spaces. -It\[aq]s useful for adjusting the execution environment or memory usage. -For a list of possible interpreter options, enter \f[V]java -h\f[R] or -\f[V]java -X\f[R] at the command line. -.PP -These options can appear for all commands operating on a keystore: -.TP -\f[V]-storetype\f[R] \f[I]storetype\f[R] -This qualifier specifies the type of keystore to be instantiated. -.TP -\f[V]-keystore\f[R] \f[I]keystore\f[R] -The keystore location. -.RS -.PP -If the JKS \f[V]storetype\f[R] is used and a keystore file doesn\[aq]t -yet exist, then certain \f[V]keytool\f[R] commands can result in a new -keystore file being created. -For example, if \f[V]keytool -genkeypair\f[R] is called and the -\f[V]-keystore\f[R] option isn\[aq]t specified, the default keystore -file named \f[V].keystore\f[R] is created in the user\[aq]s home -directory if it doesn\[aq]t already exist. -Similarly, if the \f[V]-keystore ks_file\f[R] option is specified but -\f[V]ks_file\f[R] doesn\[aq]t exist, then it is created. -For more information on the JKS \f[V]storetype\f[R], see the -\f[B]KeyStore Implementation\f[R] section in \f[B]KeyStore aliases\f[R]. -.PP -Note that the input stream from the \f[V]-keystore\f[R] option is passed -to the \f[V]KeyStore.load\f[R] method. -If \f[V]NONE\f[R] is specified as the URL, then a null stream is passed -to the \f[V]KeyStore.load\f[R] method. -\f[V]NONE\f[R] should be specified if the keystore isn\[aq]t file-based. -For example, when the keystore resides on a hardware token device. -.RE -.TP -\f[V]-cacerts\f[R] \f[I]cacerts\f[R] -Operates on the \f[I]cacerts\f[R] keystore . -This option is equivalent to \f[V]-keystore\f[R] -\f[I]path_to_cacerts\f[R] \f[V]-storetype\f[R] -\f[I]type_of_cacerts\f[R]. -An error is reported if the \f[V]-keystore\f[R] or \f[V]-storetype\f[R] -option is used with the \f[V]-cacerts\f[R] option. -.TP -\f[V]-storepass\f[R] [\f[V]:env\f[R] | \f[V]:file\f[R] ] \f[I]argument\f[R] -The password that is used to protect the integrity of the keystore. -.RS -.PP -If the modifier \f[V]env\f[R] or \f[V]file\f[R] isn\[aq]t specified, -then the password has the value \f[I]argument\f[R], which must contain -at least six characters. -Otherwise, the password is retrieved as follows: -.IP \[bu] 2 -\f[V]env\f[R]: Retrieve the password from the environment variable named -\f[I]argument\f[R]. -.IP \[bu] 2 -\f[V]file\f[R]: Retrieve the password from the file named -\f[I]argument\f[R]. -.PP -\f[B]Note:\f[R] All other options that require passwords, such as -\f[V]-keypass\f[R], \f[V]-srckeypass\f[R], \f[V]-destkeypass\f[R], -\f[V]-srcstorepass\f[R], and \f[V]-deststorepass\f[R], accept the -\f[V]env\f[R] and \f[V]file\f[R] modifiers. -Remember to separate the password option and the modifier with a colon -(:). -.PP -The password must be provided to all commands that access the keystore -contents. -For such commands, when the \f[V]-storepass\f[R] option isn\[aq]t -provided at the command line, the user is prompted for it. -.PP -When retrieving information from the keystore, the password is optional. -If a password is not specified, then the integrity of the retrieved -information can\[aq]t be verified and a warning is displayed. -.RE -.TP -\f[V]-providername\f[R] \f[I]name\f[R] -Used to identify a cryptographic service provider\[aq]s name when listed -in the security properties file. -.TP -\f[V]-addprovider\f[R] \f[I]name\f[R] -Used to add a security provider by name (such as SunPKCS11) . -.TP -\f[V]-providerclass\f[R] \f[I]class\f[R] -Used to specify the name of a cryptographic service provider\[aq]s -master class file when the service provider isn\[aq]t listed in the -security properties file. -.TP -\f[V]-providerpath\f[R] \f[I]list\f[R] -Used to specify the provider classpath. -.TP -\f[V]-providerarg\f[R] \f[I]arg\f[R] -Used with the \f[V]-addprovider\f[R] or \f[V]-providerclass\f[R] option -to represent an optional string input argument for the constructor of -\f[I]class\f[R] name. -.TP -\f[V]-protected=true\f[R]|\f[V]false\f[R] -Specify this value as \f[V]true\f[R] when a password must be specified -by way of a protected authentication path, such as a dedicated PIN -reader. -Because there are two keystores involved in the -\f[V]-importkeystore\f[R] command, the following two options, -\f[V]-srcprotected\f[R] and \f[V]-destprotected\f[R], are provided for -the source keystore and the destination keystore respectively. -.TP -\f[V]-ext\f[R] {\f[I]name\f[R]{\f[V]:critical\f[R]} {\f[V]=\f[R]\f[I]value\f[R]}} -Denotes an X.509 certificate extension. -The option can be used in \f[V]-genkeypair\f[R] and \f[V]-gencert\f[R] -to embed extensions into the generated certificate, or in -\f[V]-certreq\f[R] to show what extensions are requested in the -certificate request. -The option can appear multiple times. -The \f[I]name\f[R] argument can be a supported extension name (see -\f[B]Supported Named Extensions\f[R]) or an arbitrary OID number. -The \f[I]value\f[R] argument, when provided, denotes the argument for -the extension. -When \f[I]value\f[R] is omitted, the default value of the extension or -the extension itself requires no argument. -The \f[V]:critical\f[R] modifier, when provided, means the -extension\[aq]s \f[V]isCritical\f[R] attribute is \f[V]true\f[R]; -otherwise, it is \f[V]false\f[R]. -You can use \f[V]:c\f[R] in place of \f[V]:critical\f[R]. -.TP -\f[V]-conf\f[R] \f[I]file\f[R] -Specifies a pre-configured options file. -.SH PRE-CONFIGURED OPTIONS FILE -.PP -A pre-configured options file is a Java properties file that can be -specified with the \f[V]-conf\f[R] option. -Each property represents the default option(s) for a keytool command -using \[dq]keytool.\f[I]command_name\f[R]\[dq] as the property name. -A special property named \[dq]keytool.all\[dq] represents the default -option(s) applied to all commands. -A property value can include \f[V]${prop}\f[R] which will be expanded to -the system property associated with it. -If an option value includes white spaces inside, it should be surrounded -by quotation marks (\[dq] or \[aq]). -All property names must be in lower case. -.PP -When \f[V]keytool\f[R] is launched with a pre-configured options file, -the value for \[dq]keytool.all\[dq] (if it exists) is prepended to the -\f[V]keytool\f[R] command line first, with the value for the command -name (if it exists) comes next, and the existing options on the command -line at last. -For a single-valued option, this allows the property for a specific -command to override the \[dq]keytool.all\[dq] value, and the value -specified on the command line to override both. -For multiple-valued options, all of them will be used by -\f[V]keytool\f[R]. -.PP -For example, given the following file named \f[V]preconfig\f[R]: -.IP -.nf -\f[CB] - # A tiny pre-configured options file - keytool.all = -keystore ${user.home}/ks - keytool.list = -v - keytool.genkeypair = -keyalg rsa -\f[R] -.fi -.PP -\f[V]keytool -conf preconfig -list\f[R] is identical to -.RS -.PP -\f[V]keytool -keystore \[ti]/ks -v -list\f[R] -.RE -.PP -\f[V]keytool -conf preconfig -genkeypair -alias me\f[R] is identical to -.RS -.PP -\f[V]keytool -keystore \[ti]/ks -keyalg rsa -genkeypair -alias me\f[R] -.RE -.PP -\f[V]keytool -conf preconfig -genkeypair -alias you -keyalg ec\f[R] is -identical to -.RS -.PP -\f[V]keytool -keystore \[ti]/ks -keyalg rsa -genkeypair -alias you -keyalg ec\f[R] -.RE -.PP -which is equivalent to -.RS -.PP -\f[V]keytool -keystore \[ti]/ks -genkeypair -alias you -keyalg ec\f[R] -.RE -.PP -because \f[V]-keyalg\f[R] is a single-valued option and the \f[V]ec\f[R] -value specified on the command line overrides the preconfigured options -file. -.SH EXAMPLES OF OPTION VALUES -.PP -The following examples show the defaults for various option values: -.IP -.nf -\f[CB] --alias \[dq]mykey\[dq] - --keysize - 2048 (when using -genkeypair and -keyalg is \[dq]DSA\[dq]) - 3072 (when using -genkeypair and -keyalg is \[dq]RSA\[dq], \[dq]RSASSA-PSS\[dq], or \[dq]DH\[dq]) - 384 (when using -genkeypair and -keyalg is \[dq]EC\[dq]) - 56 (when using -genseckey and -keyalg is \[dq]DES\[dq]) - 168 (when using -genseckey and -keyalg is \[dq]DESede\[dq]) - --groupname - ed25519 (when using -genkeypair and -keyalg is \[dq]EdDSA\[dq], key size is 255) - x25519 (when using -genkeypair and -keyalg is \[dq]XDH\[dq], key size is 255) - --validity 90 - --keystore - --destkeystore - --storetype - --file - stdin (if reading) - stdout (if writing) - --protected false -\f[R] -.fi -.PP -When generating a certificate or a certificate request, the default -signature algorithm (\f[V]-sigalg\f[R] option) is derived from the -algorithm of the underlying private key to provide an appropriate level -of security strength as follows: -.PP -Default Signature Algorithms -.TS -tab(@); -l l l. -T{ -keyalg -T}@T{ -key size -T}@T{ -default sigalg -T} -_ -T{ -DSA -T}@T{ -any size -T}@T{ -SHA256withDSA -T} -T{ -RSA -T}@T{ -< 624 -T}@T{ -SHA256withRSA (key size is too small for using SHA-384) -T} -T{ -T}@T{ -<= 7680 -T}@T{ -SHA384withRSA -T} -T{ -T}@T{ -> 7680 -T}@T{ -SHA512withRSA -T} -T{ -EC -T}@T{ -< 512 -T}@T{ -SHA384withECDSA -T} -T{ -T}@T{ ->= 512 -T}@T{ -SHA512withECDSA -T} -T{ -RSASSA-PSS -T}@T{ -< 624 -T}@T{ -RSASSA-PSS (with SHA-256, key size is too small for -T} -T{ -T}@T{ -T}@T{ -using SHA-384) -T} -T{ -T}@T{ -<= 7680 -T}@T{ -RSASSA-PSS (with SHA-384) -T} -T{ -T}@T{ -> 7680 -T}@T{ -RSASSA-PSS (with SHA-512) -T} -T{ -EdDSA -T}@T{ -255 -T}@T{ -Ed25519 -T} -T{ -T}@T{ -448 -T}@T{ -Ed448 -T} -T{ -Ed25519 -T}@T{ -255 -T}@T{ -Ed25519 -T} -T{ -Ed448 -T}@T{ -448 -T}@T{ -Ed448 -T} -.TE -.IP \[bu] 2 -The key size, measured in bits, corresponds to the size of the private -key. -This size is determined by the value of the \f[V]-keysize\f[R] or -\f[V]-groupname\f[R] options or the value derived from a default -setting. -.IP \[bu] 2 -An RSASSA-PSS signature algorithm uses a \f[V]MessageDigest\f[R] -algorithm as its hash and MGF1 algorithms. -.IP \[bu] 2 -If neither a default \f[V]-keysize\f[R] or \f[V]-groupname\f[R] is -defined for an algorithm, the security provider will choose a default -setting. -.PP -\f[B]Note:\f[R] -.PP -To improve out of the box security, default keysize, groupname, and -signature algorithm names are periodically updated to stronger values -with each release of the JDK. -If interoperability with older releases of the JDK is important, make -sure that the defaults are supported by those releases. -Alternatively, you can use the \f[V]-keysize\f[R], \f[V]-groupname\f[R], -or \f[V]-sigalg\f[R] options to override the default values at your own -risk. -.SH SUPPORTED NAMED EXTENSIONS -.PP -The \f[V]keytool\f[R] command supports these named extensions. -The names aren\[aq]t case-sensitive. -.TP -\f[V]BC\f[R] or \f[V]BasicConstraints\f[R] -Values: -.RS -.PP -The full form is -\f[V]ca:\f[R]{\f[V]true\f[R]|\f[V]false\f[R]}[\f[V],pathlen:\f[R]\f[I]len\f[R]] -or \f[I]len\f[R], which is short for -\f[V]ca:true,pathlen:\f[R]\f[I]len\f[R]. -.PP -When \f[I]len\f[R] is omitted, the resulting value is \f[V]ca:true\f[R]. -.RE -.TP -\f[V]KU\f[R] or \f[V]KeyUsage\f[R] -Values: -.RS -.PP -\f[I]usage\f[R](\f[V],\f[R] \f[I]usage\f[R])* -.PP -\f[I]usage\f[R] can be one of the following: -.IP \[bu] 2 -\f[V]digitalSignature\f[R] -.IP \[bu] 2 -\f[V]nonRepudiation\f[R] (\f[V]contentCommitment\f[R]) -.IP \[bu] 2 -\f[V]keyEncipherment\f[R] -.IP \[bu] 2 -\f[V]dataEncipherment\f[R] -.IP \[bu] 2 -\f[V]keyAgreement\f[R] -.IP \[bu] 2 -\f[V]keyCertSign\f[R] -.IP \[bu] 2 -\f[V]cRLSign\f[R] -.IP \[bu] 2 -\f[V]encipherOnly\f[R] -.IP \[bu] 2 -\f[V]decipherOnly\f[R] -.PP -Provided there is no ambiguity, the \f[I]usage\f[R] argument can be -abbreviated with the first few letters (such as \f[V]dig\f[R] for -\f[V]digitalSignature\f[R]) or in camel-case style (such as \f[V]dS\f[R] -for \f[V]digitalSignature\f[R] or \f[V]cRLS\f[R] for \f[V]cRLSign\f[R]). -The \f[I]usage\f[R] values are case-sensitive. -.RE -.TP -\f[V]EKU\f[R] or \f[V]ExtendedKeyUsage\f[R] -Values: -.RS -.PP -\f[I]usage\f[R](\f[V],\f[R] \f[I]usage\f[R])* -.PP -\f[I]usage\f[R] can be one of the following: -.IP \[bu] 2 -\f[V]anyExtendedKeyUsage\f[R] -.IP \[bu] 2 -\f[V]serverAuth\f[R] -.IP \[bu] 2 -\f[V]clientAuth\f[R] -.IP \[bu] 2 -\f[V]codeSigning\f[R] -.IP \[bu] 2 -\f[V]emailProtection\f[R] -.IP \[bu] 2 -\f[V]timeStamping\f[R] -.IP \[bu] 2 -\f[V]OCSPSigning\f[R] -.IP \[bu] 2 -Any OID string -.PP -Provided there is no ambiguity, the \f[I]usage\f[R] argument can be -abbreviated with the first few letters or in camel-case style. -The \f[I]usage\f[R] values are case-sensitive. -.RE -.TP -\f[V]SAN\f[R] or \f[V]SubjectAlternativeName\f[R] -Values: -.RS -.PP -\f[I]type\f[R]\f[V]:\f[R]\f[I]value\f[R](\f[V],\f[R] -\f[I]type\f[R]\f[V]:\f[R]\f[I]value\f[R])* -.PP -\f[I]type\f[R] can be one of the following: -.IP \[bu] 2 -\f[V]EMAIL\f[R] -.IP \[bu] 2 -\f[V]URI\f[R] -.IP \[bu] 2 -\f[V]DNS\f[R] -.IP \[bu] 2 -\f[V]IP\f[R] -.IP \[bu] 2 -\f[V]OID\f[R] -.PP -The \f[I]value\f[R] argument is the string format value for the -\f[I]type\f[R]. -.RE -.TP -\f[V]IAN\f[R] or \f[V]IssuerAlternativeName\f[R] -Values: -.RS -.PP -Same as \f[V]SAN\f[R] or \f[V]SubjectAlternativeName\f[R]. -.RE -.TP -\f[V]SIA\f[R] or \f[V]SubjectInfoAccess\f[R] -Values: -.RS -.PP -\f[I]method\f[R]\f[V]:\f[R]\f[I]location-type\f[R]\f[V]:\f[R]\f[I]location-value\f[R](\f[V],\f[R] -\f[I]method\f[R]\f[V]:\f[R]\f[I]location-type\f[R]\f[V]:\f[R]\f[I]location-value\f[R])* -.PP -\f[I]method\f[R] can be one of the following: -.IP \[bu] 2 -\f[V]timeStamping\f[R] -.IP \[bu] 2 -\f[V]caRepository\f[R] -.IP \[bu] 2 -Any OID -.PP -The \f[I]location-type\f[R] and \f[I]location-value\f[R] arguments can -be any \f[I]type\f[R]\f[V]:\f[R]\f[I]value\f[R] supported by the -\f[V]SubjectAlternativeName\f[R] extension. -.RE -.TP -\f[V]AIA\f[R] or \f[V]AuthorityInfoAccess\f[R] -Values: -.RS -.PP -Same as \f[V]SIA\f[R] or \f[V]SubjectInfoAccess\f[R]. -.PP -The \f[I]method\f[R] argument can be one of the following: -.IP \[bu] 2 -\f[V]ocsp\f[R] -.IP \[bu] 2 -\f[V]caIssuers\f[R] -.IP \[bu] 2 -Any OID -.RE -.PP -When \f[I]name\f[R] is OID, the value is the hexadecimal dumped Definite -Encoding Rules (DER) encoding of the \f[V]extnValue\f[R] for the -extension excluding the OCTET STRING type and length bytes. -Other than standard hexadecimal numbers (0-9, a-f, A-F), any extra -characters are ignored in the HEX string. -Therefore, both 01:02:03:04 and 01020304 are accepted as identical -values. -When there is no value, the extension has an empty value field. -.PP -A special name \f[V]honored\f[R], used only in \f[V]-gencert\f[R], -denotes how the extensions included in the certificate request should be -honored. -The value for this name is a comma-separated list of \f[V]all\f[R] (all -requested extensions are honored), -\f[I]name\f[R]{\f[V]:\f[R][\f[V]critical\f[R]|\f[V]non-critical\f[R]]} -(the named extension is honored, but it uses a different -\f[V]isCritical\f[R] attribute), and \f[V]-name\f[R] (used with -\f[V]all\f[R], denotes an exception). -Requested extensions aren\[aq]t honored by default. -.PP -If, besides the\f[V]-ext honored\f[R] option, another named or OID -\f[V]-ext\f[R] option is provided, this extension is added to those -already honored. -However, if this name (or OID) also appears in the honored value, then -its value and criticality override that in the request. -If an extension of the same type is provided multiple times through -either a name or an OID, only the last extension is used. -.PP -The \f[V]subjectKeyIdentifier\f[R] extension is always created. -For non-self-signed certificates, the \f[V]authorityKeyIdentifier\f[R] -is created. -.PP -\f[B]CAUTION:\f[R] -.PP -Users should be aware that some combinations of extensions (and other -certificate fields) may not conform to the Internet standard. -See \f[B]Certificate Conformance Warning\f[R]. -.SH EXAMPLES OF TASKS IN CREATING A KEYSTORE -.PP -The following examples describe the sequence actions in creating a -keystore for managing public/private key pairs and certificates from -trusted entities. -.IP \[bu] 2 -\f[B]Generating the Key Pair\f[R] -.IP \[bu] 2 -\f[B]Requesting a Signed Certificate from a CA\f[R] -.IP \[bu] 2 -\f[B]Importing a Certificate for the CA\f[R] -.IP \[bu] 2 -\f[B]Importing the Certificate Reply from the CA\f[R] -.IP \[bu] 2 -\f[B]Exporting a Certificate That Authenticates the Public Key\f[R] -.IP \[bu] 2 -\f[B]Importing the Keystore\f[R] -.IP \[bu] 2 -\f[B]Generating Certificates for an SSL Server\f[R] -.SH GENERATING THE KEY PAIR -.PP -Create a keystore and then generate the key pair. -.PP -You can enter the command as a single line such as the following: -.RS -.PP -\f[V]keytool -genkeypair -dname \[dq]cn=myname, ou=mygroup, o=mycompany, c=mycountry\[dq] -alias business -keyalg rsa -keypass\f[R] -\f[I]password\f[R] -\f[V]-keystore /working/mykeystore -storepass password -validity 180\f[R] -.RE -.PP -The command creates the keystore named \f[V]mykeystore\f[R] in the -working directory (provided it doesn\[aq]t already exist), and assigns -it the password specified by \f[V]-keypass\f[R]. -It generates a public/private key pair for the entity whose -distinguished name is \f[V]myname\f[R], \f[V]mygroup\f[R], -\f[V]mycompany\f[R], and a two-letter country code of -\f[V]mycountry\f[R]. -It uses the RSA key generation algorithm to create the keys; both are -3072 bits. -.PP -The command uses the default SHA384withRSA signature algorithm to create -a self-signed certificate that includes the public key and the -distinguished name information. -The certificate is valid for 180 days, and is associated with the -private key in a keystore entry referred to by -\f[V]-alias business\f[R]. -The private key is assigned the password specified by -\f[V]-keypass\f[R]. -.PP -The command is significantly shorter when the option defaults are -accepted. -In this case, only \f[V]-keyalg\f[R] is required, and the defaults are -used for unspecified options that have default values. -You are prompted for any required values. -You could have the following: -.RS -.PP -\f[V]keytool -genkeypair -keyalg rsa\f[R] -.RE -.PP -In this case, a keystore entry with the alias \f[V]mykey\f[R] is -created, with a newly generated key pair and a certificate that is valid -for 90 days. -This entry is placed in your home directory in a keystore named -\f[V].keystore\f[R] . -\f[V].keystore\f[R] is created if it doesn\[aq]t already exist. -You are prompted for the distinguished name information, the keystore -password, and the private key password. -.PP -\f[B]Note:\f[R] -.PP -The rest of the examples assume that you responded to the prompts with -values equal to those specified in the first \f[V]-genkeypair\f[R] -command. -For example, a distinguished name of -\f[V]cn=\f[R]\f[I]myname\f[R]\f[V], ou=\f[R]\f[I]mygroup\f[R]\f[V], o=\f[R]\f[I]mycompany\f[R]\f[V], c=\f[R]\f[I]mycountry\f[R]). -.SH REQUESTING A SIGNED CERTIFICATE FROM A CA -.PP -\f[B]Note:\f[R] -.PP -Generating the key pair created a self-signed certificate; however, a -certificate is more likely to be trusted by others when it is signed by -a CA. -.PP -To get a CA signature, complete the following process: -.IP "1." 3 -Generate a CSR: -.RS 4 -.RS -.PP -\f[V]keytool -certreq -file myname.csr\f[R] -.RE -.PP -This creates a CSR for the entity identified by the default alias -\f[V]mykey\f[R] and puts the request in the file named -\f[V]myname.csr\f[R]. -.RE -.IP "2." 3 -Submit \f[V]myname.csr\f[R] to a CA, such as DigiCert. -.PP -The CA authenticates you, the requestor (usually offline), and returns a -certificate, signed by them, authenticating your public key. -In some cases, the CA returns a chain of certificates, each one -authenticating the public key of the signer of the previous certificate -in the chain. -.SH IMPORTING A CERTIFICATE FOR THE CA -.PP -To import a certificate for the CA, complete the following process: -.IP "1." 3 -Before you import the certificate reply from a CA, you need one or more -trusted certificates either in your keystore or in the \f[V]cacerts\f[R] -keystore file. -See \f[V]-importcert\f[R] in \f[B]Commands\f[R]. -.RS 4 -.IP \[bu] 2 -If the certificate reply is a certificate chain, then you need the top -certificate of the chain. -The root CA certificate that authenticates the public key of the CA. -.IP \[bu] 2 -If the certificate reply is a single certificate, then you need a -certificate for the issuing CA (the one that signed it). -If that certificate isn\[aq]t self-signed, then you need a certificate -for its signer, and so on, up to a self-signed root CA certificate. -.PP -The \f[V]cacerts\f[R] keystore ships with a set of root certificates -issued by the CAs of \f[B]the Oracle Java Root Certificate program\f[R] -[http://www.oracle.com/technetwork/java/javase/javasecarootcertsprogram-1876540.html]. -If you request a signed certificate from a CA, and a certificate -authenticating that CA\[aq]s public key hasn\[aq]t been added to -\f[V]cacerts\f[R], then you must import a certificate from that CA as a -trusted certificate. -.PP -A certificate from a CA is usually self-signed or signed by another CA. -If it is signed by another CA, you need a certificate that authenticates -that CA\[aq]s public key. -.PP -For example, you have obtained a \f[I]X\f[R]\f[V].cer\f[R] file from a -company that is a CA and the file is supposed to be a self-signed -certificate that authenticates that CA\[aq]s public key. -Before you import it as a trusted certificate, you should ensure that -the certificate is valid by: -.IP "1." 3 -Viewing it with the \f[V]keytool -printcert\f[R] command or the -\f[V]keytool -importcert\f[R] command without using the -\f[V]-noprompt\f[R] option. -Make sure that the displayed certificate fingerprints match the expected -fingerprints. -.IP "2." 3 -Calling the person who sent the certificate, and comparing the -fingerprints that you see with the ones that they show or that a secure -public key repository shows. -.PP -Only when the fingerprints are equal is it assured that the certificate -wasn\[aq]t replaced in transit with somebody else\[aq]s certificate -(such as an attacker\[aq]s certificate). -If such an attack takes place, and you didn\[aq]t check the certificate -before you imported it, then you would be trusting anything that the -attacker signed. -.RE -.IP "2." 3 -Replace the self-signed certificate with a certificate chain, where each -certificate in the chain authenticates the public key of the signer of -the previous certificate in the chain, up to a root CA. -.RS 4 -.PP -If you trust that the certificate is valid, then you can add it to your -keystore by entering the following command: -.RS -.PP -\f[V]keytool -importcert -alias\f[R] \f[I]alias\f[R] -\f[V]-file *X*\f[R].cer\[ga] -.RE -.PP -This command creates a trusted certificate entry in the keystore from -the data in the CA certificate file and assigns the values of the -\f[I]alias\f[R] to the entry. -.RE -.SH IMPORTING THE CERTIFICATE REPLY FROM THE CA -.PP -After you import a certificate that authenticates the public key of the -CA that you submitted your certificate signing request to (or there is -already such a certificate in the \f[V]cacerts\f[R] file), you can -import the certificate reply and replace your self-signed certificate -with a certificate chain. -.PP -The certificate chain is one of the following: -.IP \[bu] 2 -Returned by the CA when the CA reply is a chain. -.IP \[bu] 2 -Constructed when the CA reply is a single certificate. -This certificate chain is constructed by using the certificate reply and -trusted certificates available either in the keystore where you import -the reply or in the \f[V]cacerts\f[R] keystore file. -.PP -For example, if you sent your certificate signing request to DigiCert, -then you can import their reply by entering the following command: -.PP -\f[B]Note:\f[R] -.PP -In this example, the returned certificate is named -\f[V]DCmyname.cer\f[R]. -.RS -.PP -\f[V]keytool -importcert -trustcacerts -file DCmyname.cer\f[R] -.RE -.SH EXPORTING A CERTIFICATE THAT AUTHENTICATES THE PUBLIC KEY -.PP -\f[B]Note:\f[R] -.PP -If you used the \f[V]jarsigner\f[R] command to sign a Java Archive (JAR) -file, then clients that use the file will want to authenticate your -signature. -.PP -One way that clients can authenticate you is by importing your public -key certificate into their keystore as a trusted entry. -You can then export the certificate and supply it to your clients. -.PP -For example: -.IP "1." 3 -Copy your certificate to a file named \f[V]myname.cer\f[R] by entering -the following command: -.RS 4 -.PP -\f[B]Note:\f[R] -.PP -In this example, the entry has an alias of \f[V]mykey\f[R]. -.RS -.PP -\f[V]keytool -exportcert -alias mykey -file myname.cer\f[R] -.RE -.RE -.IP "2." 3 -With the certificate and the signed JAR file, a client can use the -\f[V]jarsigner\f[R] command to authenticate your signature. -.SH IMPORTING THE KEYSTORE -.PP -Use the \f[V]importkeystore\f[R] command to import an entire keystore -into another keystore. -This imports all entries from the source keystore, including keys and -certificates, to the destination keystore with a single command. -You can use this command to import entries from a different type of -keystore. -During the import, all new entries in the destination keystore will have -the same alias names and protection passwords (for secret keys and -private keys). -If the \f[V]keytool\f[R] command can\[aq]t recover the private keys or -secret keys from the source keystore, then it prompts you for a -password. -If it detects alias duplication, then it asks you for a new alias, and -you can specify a new alias or simply allow the \f[V]keytool\f[R] -command to overwrite the existing one. -.PP -For example, import entries from a typical JKS type keystore -\f[V]key.jks\f[R] into a PKCS #11 type hardware-based keystore, by -entering the following command: -.RS -.PP -\f[V]keytool -importkeystore -srckeystore key.jks -destkeystore NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass\f[R] -\f[I]password\f[R] \f[V]-deststorepass\f[R] \f[I]password\f[R] -.RE -.PP -The \f[V]importkeystore\f[R] command can also be used to import a single -entry from a source keystore to a destination keystore. -In this case, besides the options you used in the previous example, you -need to specify the alias you want to import. -With the \f[V]-srcalias\f[R] option specified, you can also specify the -destination alias name, protection password for a secret or private key, -and the destination protection password you want as follows: -.RS -.PP -\f[V]keytool -importkeystore -srckeystore key.jks -destkeystore NONE -srcstoretype JKS -deststoretype PKCS11 -srcstorepass\f[R] -\f[I]password\f[R] \f[V]-deststorepass\f[R] \f[I]password\f[R] -\f[V]-srcalias myprivatekey -destalias myoldprivatekey -srckeypass\f[R] -\f[I]password\f[R] \f[V]-destkeypass\f[R] \f[I]password\f[R] -\f[V]-noprompt\f[R] -.RE -.SH GENERATING CERTIFICATES FOR AN SSL SERVER -.PP -The following are \f[V]keytool\f[R] commands used to generate key pairs -and certificates for three entities: -.IP \[bu] 2 -Root CA (\f[V]root\f[R]) -.IP \[bu] 2 -Intermediate CA (\f[V]ca\f[R]) -.IP \[bu] 2 -SSL server (\f[V]server\f[R]) -.PP -Ensure that you store all the certificates in the same keystore. -.IP -.nf -\f[CB] -keytool -genkeypair -keystore root.jks -alias root -ext bc:c -keyalg rsa -keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c -keyalg rsa -keytool -genkeypair -keystore server.jks -alias server -keyalg rsa - -keytool -keystore root.jks -alias root -exportcert -rfc > root.pem - -keytool -storepass password -keystore ca.jks -certreq -alias ca | - keytool -storepass password -keystore root.jks - -gencert -alias root -ext BC=0 -rfc > ca.pem -keytool -keystore ca.jks -importcert -alias ca -file ca.pem - -keytool -storepass password -keystore server.jks -certreq -alias server | - keytool -storepass password -keystore ca.jks -gencert -alias ca - -ext ku:c=dig,kE -rfc > server.pem -cat root.pem ca.pem server.pem | - keytool -keystore server.jks -importcert -alias server -\f[R] -.fi -.SH TERMS -.TP -Keystore -A keystore is a storage facility for cryptographic keys and -certificates. -.TP -Keystore entries -Keystores can have different types of entries. -The two most applicable entry types for the \f[V]keytool\f[R] command -include the following: -.RS -.PP -Key entries: Each entry holds very sensitive cryptographic key -information, which is stored in a protected format to prevent -unauthorized access. -Typically, a key stored in this type of entry is a secret key, or a -private key accompanied by the certificate chain for the corresponding -public key. -See \f[B]Certificate Chains\f[R]. -The \f[V]keytool\f[R] command can handle both types of entries, while -the \f[V]jarsigner\f[R] tool only handles the latter type of entry, that -is private keys and their associated certificate chains. -.PP -Trusted certificate entries: Each entry contains a single public key -certificate that belongs to another party. -The entry is called a trusted certificate because the keystore owner -trusts that the public key in the certificate belongs to the identity -identified by the subject (owner) of the certificate. -The issuer of the certificate vouches for this, by signing the -certificate. -.RE -.TP -Keystore aliases -All keystore entries (key and trusted certificate entries) are accessed -by way of unique aliases. -.RS -.PP -An alias is specified when you add an entity to the keystore with the -\f[V]-genseckey\f[R] command to generate a secret key, the -\f[V]-genkeypair\f[R] command to generate a key pair (public and private -key), or the \f[V]-importcert\f[R] command to add a certificate or -certificate chain to the list of trusted certificates. -Subsequent \f[V]keytool\f[R] commands must use this same alias to refer -to the entity. -.PP -For example, you can use the alias \f[V]duke\f[R] to generate a new -public/private key pair and wrap the public key into a self-signed -certificate with the following command. -See \f[B]Certificate Chains\f[R]. -.RS -.PP -\f[V]keytool -genkeypair -alias duke -keyalg rsa -keypass\f[R] -\f[I]passwd\f[R] -.RE -.PP -This example specifies an initial \f[I]passwd\f[R] required by -subsequent commands to access the private key associated with the alias -\f[V]duke\f[R]. -If you later want to change Duke\[aq]s private key password, use a -command such as the following: -.RS -.PP -\f[V]keytool -keypasswd -alias duke -keypass\f[R] \f[I]passwd\f[R] -\f[V]-new\f[R] \f[I]newpasswd\f[R] -.RE -.PP -This changes the initial \f[I]passwd\f[R] to \f[I]newpasswd\f[R]. -A password shouldn\[aq]t be specified on a command line or in a script -unless it is for testing purposes, or you are on a secure system. -If you don\[aq]t specify a required password option on a command line, -then you are prompted for it. -.RE -.TP -Keystore implementation -The \f[V]KeyStore\f[R] class provided in the \f[V]java.security\f[R] -package supplies well-defined interfaces to access and modify the -information in a keystore. -It is possible for there to be multiple different concrete -implementations, where each implementation is that for a particular type -of keystore. -.RS -.PP -Currently, two command-line tools (\f[V]keytool\f[R] and -\f[V]jarsigner\f[R]) make use of keystore implementations. -Because the \f[V]KeyStore\f[R] class is \f[V]public\f[R], users can -write additional security applications that use it. -.PP -In JDK 9 and later, the default keystore implementation is -\f[V]PKCS12\f[R]. -This is a cross platform keystore based on the RSA PKCS12 Personal -Information Exchange Syntax Standard. -This standard is primarily meant for storing or transporting a -user\[aq]s private keys, certificates, and miscellaneous secrets. -There is another built-in implementation, provided by Oracle. -It implements the keystore as a file with a proprietary keystore type -(format) named \f[V]JKS\f[R]. -It protects each private key with its individual password, and also -protects the integrity of the entire keystore with a (possibly -different) password. -.PP -Keystore implementations are provider-based. -More specifically, the application interfaces supplied by -\f[V]KeyStore\f[R] are implemented in terms of a Service Provider -Interface (SPI). -That is, there is a corresponding abstract \f[V]KeystoreSpi\f[R] class, -also in the \f[V]java.security package\f[R], which defines the Service -Provider Interface methods that providers must implement. -The term \f[I]provider\f[R] refers to a package or a set of packages -that supply a concrete implementation of a subset of services that can -be accessed by the Java Security API. -To provide a keystore implementation, clients must implement a provider -and supply a \f[V]KeystoreSpi\f[R] subclass implementation, as described -in Steps to Implement and Integrate a Provider. -.PP -Applications can choose different types of keystore implementations from -different providers, using the \f[V]getInstance\f[R] factory method -supplied in the \f[V]KeyStore\f[R] class. -A keystore type defines the storage and data format of the keystore -information, and the algorithms used to protect private/secret keys in -the keystore and the integrity of the keystore. -Keystore implementations of different types aren\[aq]t compatible. -.PP -The \f[V]keytool\f[R] command works on any file-based keystore -implementation. -It treats the keystore location that is passed to it at the command line -as a file name and converts it to a \f[V]FileInputStream\f[R], from -which it loads the keystore information.)The \f[V]jarsigner\f[R] -commands can read a keystore from any location that can be specified -with a URL. -.PP -For \f[V]keytool\f[R] and \f[V]jarsigner\f[R], you can specify a -keystore type at the command line, with the \f[V]-storetype\f[R] option. -.PP -If you don\[aq]t explicitly specify a keystore type, then the tools -choose a keystore implementation based on the value of the -\f[V]keystore.type\f[R] property specified in the security properties -file. -The security properties file is called \f[V]java.security\f[R], and -resides in the security properties directory: -.IP \[bu] 2 -\f[B]Linux and macOS:\f[R] \f[V]java.home/lib/security\f[R] -.IP \[bu] 2 -\f[B]Windows:\f[R] \f[V]java.home\[rs]lib\[rs]security\f[R] -.PP -Each tool gets the \f[V]keystore.type\f[R] value and then examines all -the currently installed providers until it finds one that implements a -keystores of that type. -It then uses the keystore implementation from that provider.The -\f[V]KeyStore\f[R] class defines a static method named -\f[V]getDefaultType\f[R] that lets applications retrieve the value of -the \f[V]keystore.type\f[R] property. -The following line of code creates an instance of the default keystore -type as specified in the \f[V]keystore.type\f[R] property: -.RS -.PP -\f[V]KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());\f[R] -.RE -.PP -The default keystore type is \f[V]pkcs12\f[R], which is a cross-platform -keystore based on the RSA PKCS12 Personal Information Exchange Syntax -Standard. -This is specified by the following line in the security properties file: -.RS -.PP -\f[V]keystore.type=pkcs12\f[R] -.RE -.PP -To have the tools utilize a keystore implementation other than the -default, you can change that line to specify a different keystore type. -For example, if you want to use the Oracle\[aq]s \f[V]jks\f[R] keystore -implementation, then change the line to the following: -.RS -.PP -\f[V]keystore.type=jks\f[R] -.RE -.PP -\f[B]Note:\f[R] -.PP -Case doesn\[aq]t matter in keystore type designations. -For example, \f[V]JKS\f[R] would be considered the same as -\f[V]jks\f[R]. -.RE -.TP -Certificate -A certificate (or public-key certificate) is a digitally signed -statement from one entity (the issuer), saying that the public key and -some other information of another entity (the subject) has some specific -value. -The following terms are related to certificates: -.RS -.IP \[bu] 2 -Public Keys: These are numbers associated with a particular entity, and -are intended to be known to everyone who needs to have trusted -interactions with that entity. -Public keys are used to verify signatures. -.IP \[bu] 2 -Digitally Signed: If some data is digitally signed, then it is stored -with the identity of an entity and a signature that proves that entity -knows about the data. -The data is rendered unforgeable by signing with the entity\[aq]s -private key. -.IP \[bu] 2 -Identity: A known way of addressing an entity. -In some systems, the identity is the public key, and in others it can be -anything from an Oracle Solaris UID to an email address to an X.509 -distinguished name. -.IP \[bu] 2 -Signature: A signature is computed over some data using the private key -of an entity. -The signer, which in the case of a certificate is also known as the -issuer. -.IP \[bu] 2 -Private Keys: These are numbers, each of which is supposed to be known -only to the particular entity whose private key it is (that is, it is -supposed to be kept secret). -Private and public keys exist in pairs in all public key cryptography -systems (also referred to as public key crypto systems). -In a typical public key crypto system, such as DSA, a private key -corresponds to exactly one public key. -Private keys are used to compute signatures. -.IP \[bu] 2 -Entity: An entity is a person, organization, program, computer, -business, bank, or something else you are trusting to some degree. -.PP -Public key cryptography requires access to users\[aq] public keys. -In a large-scale networked environment, it is impossible to guarantee -that prior relationships between communicating entities were established -or that a trusted repository exists with all used public keys. -Certificates were invented as a solution to this public key distribution -problem. -Now a Certification Authority (CA) can act as a trusted third party. -CAs are entities such as businesses that are trusted to sign (issue) -certificates for other entities. -It is assumed that CAs only create valid and reliable certificates -because they are bound by legal agreements. -There are many public Certification Authorities, such as DigiCert, -Comodo, Entrust, and so on. -.PP -You can also run your own Certification Authority using products such as -Microsoft Certificate Server or the Entrust CA product for your -organization. -With the \f[V]keytool\f[R] command, it is possible to display, import, -and export certificates. -It is also possible to generate self-signed certificates. -.PP -The \f[V]keytool\f[R] command currently handles X.509 certificates. -.RE -.TP -X.509 Certificates -The X.509 standard defines what information can go into a certificate -and describes how to write it down (the data format). -All the data in a certificate is encoded with two related standards -called ASN.1/DER. -Abstract Syntax Notation 1 describes data. -The Definite Encoding Rules describe a single way to store and transfer -that data. -.RS -.PP -All X.509 certificates have the following data, in addition to the -signature: -.IP \[bu] 2 -Version: This identifies which version of the X.509 standard applies to -this certificate, which affects what information can be specified in it. -Thus far, three versions are defined. -The \f[V]keytool\f[R] command can import and export v1, v2, and v3 -certificates. -It generates v3 certificates. -.RS 2 -.IP \[bu] 2 -X.509 Version 1 has been available since 1988, is widely deployed, and -is the most generic. -.IP \[bu] 2 -X.509 Version 2 introduced the concept of subject and issuer unique -identifiers to handle the possibility of reuse of subject or issuer -names over time. -Most certificate profile documents strongly recommend that names not be -reused and that certificates shouldn\[aq]t make use of unique -identifiers. -Version 2 certificates aren\[aq]t widely used. -.IP \[bu] 2 -X.509 Version 3 is the most recent (1996) and supports the notion of -extensions where anyone can define an extension and include it in the -certificate. -Some common extensions are: KeyUsage (limits the use of the keys to -particular purposes such as \f[V]signing-only\f[R]) and AlternativeNames -(allows other identities to also be associated with this public key, for -example. -DNS names, email addresses, IP addresses). -Extensions can be marked critical to indicate that the extension should -be checked and enforced or used. -For example, if a certificate has the KeyUsage extension marked critical -and set to \f[V]keyCertSign\f[R], then when this certificate is -presented during SSL communication, it should be rejected because the -certificate extension indicates that the associated private key should -only be used for signing certificates and not for SSL use. -.RE -.IP \[bu] 2 -Serial number: The entity that created the certificate is responsible -for assigning it a serial number to distinguish it from other -certificates it issues. -This information is used in numerous ways. -For example, when a certificate is revoked its serial number is placed -in a Certificate Revocation List (CRL). -.IP \[bu] 2 -Signature algorithm identifier: This identifies the algorithm used by -the CA to sign the certificate. -.IP \[bu] 2 -Issuer name: The X.500 Distinguished Name of the entity that signed the -certificate. -This is typically a CA. -Using this certificate implies trusting the entity that signed this -certificate. -In some cases, such as root or top-level CA certificates, the issuer -signs its own certificate. -.IP \[bu] 2 -Validity period: Each certificate is valid only for a limited amount of -time. -This period is described by a start date and time and an end date and -time, and can be as short as a few seconds or almost as long as a -century. -The validity period chosen depends on a number of factors, such as the -strength of the private key used to sign the certificate, or the amount -one is willing to pay for a certificate. -This is the expected period that entities can rely on the public value, -when the associated private key has not been compromised. -.IP \[bu] 2 -Subject name: The name of the entity whose public key the certificate -identifies. -This name uses the X.500 standard, so it is intended to be unique across -the Internet. -This is the X.500 Distinguished Name (DN) of the entity. -For example, -.RS 2 -.RS -.PP -\f[V]CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, C=US\f[R] -.RE -.PP -These refer to the subject\[aq]s common name (CN), organizational unit -(OU), organization (O), and country (C). -.RE -.IP \[bu] 2 -Subject public key information: This is the public key of the entity -being named with an algorithm identifier that specifies which public key -crypto system this key belongs to and any associated key parameters. -.RE -.TP -Certificate Chains -The \f[V]keytool\f[R] command can create and manage keystore key entries -that each contain a private key and an associated certificate chain. -The first certificate in the chain contains the public key that -corresponds to the private key. -.RS -.PP -When keys are first generated, the chain usually starts off containing a -single element, a self-signed certificate. -See -genkeypair in \f[B]Commands\f[R]. -A self-signed certificate is one for which the issuer (signer) is the -same as the subject. -The subject is the entity whose public key is being authenticated by the -certificate. -When the \f[V]-genkeypair\f[R] command is called to generate a new -public/private key pair, it also wraps the public key into a self-signed -certificate (unless the \f[V]-signer\f[R] option is specified). -.PP -Later, after a Certificate Signing Request (CSR) was generated with the -\f[V]-certreq\f[R] command and sent to a Certification Authority (CA), -the response from the CA is imported with \f[V]-importcert\f[R], and the -self-signed certificate is replaced by a chain of certificates. -At the bottom of the chain is the certificate (reply) issued by the CA -authenticating the subject\[aq]s public key. -The next certificate in the chain is one that authenticates the CA\[aq]s -public key. -.PP -In many cases, this is a self-signed certificate, which is a certificate -from the CA authenticating its own public key, and the last certificate -in the chain. -In other cases, the CA might return a chain of certificates. -In this case, the bottom certificate in the chain is the same (a -certificate signed by the CA, authenticating the public key of the key -entry), but the second certificate in the chain is a certificate signed -by a different CA that authenticates the public key of the CA you sent -the CSR to. -The next certificate in the chain is a certificate that authenticates -the second CA\[aq]s key, and so on, until a self-signed root certificate -is reached. -Each certificate in the chain (after the first) authenticates the public -key of the signer of the previous certificate in the chain. -.PP -Many CAs only return the issued certificate, with no supporting chain, -especially when there is a flat hierarchy (no intermediates CAs). -In this case, the certificate chain must be established from trusted -certificate information already stored in the keystore. -.PP -A different reply format (defined by the PKCS #7 standard) includes the -supporting certificate chain in addition to the issued certificate. -Both reply formats can be handled by the \f[V]keytool\f[R] command. -.PP -The top-level (root) CA certificate is self-signed. -However, the trust into the root\[aq]s public key doesn\[aq]t come from -the root certificate itself, but from other sources such as a newspaper. -This is because anybody could generate a self-signed certificate with -the distinguished name of, for example, the DigiCert root CA. -The root CA public key is widely known. -The only reason it is stored in a certificate is because this is the -format understood by most tools, so the certificate in this case is only -used as a vehicle to transport the root CA\[aq]s public key. -Before you add the root CA certificate to your keystore, you should view -it with the \f[V]-printcert\f[R] option and compare the displayed -fingerprint with the well-known fingerprint obtained from a newspaper, -the root CA\[aq]s Web page, and so on. -.RE -.TP -cacerts Certificates File -A certificates file named \f[V]cacerts\f[R] resides in the security -properties directory: -.RS -.IP \[bu] 2 -\f[B]Linux and macOS:\f[R] \f[I]JAVA_HOME\f[R]\f[V]/lib/security\f[R] -.IP \[bu] 2 -\f[B]Windows:\f[R] \f[I]JAVA_HOME\f[R]\f[V]\[rs]lib\[rs]security\f[R] -.PP -The \f[V]cacerts\f[R] file represents a system-wide keystore with CA -certificates. -System administrators can configure and manage that file with the -\f[V]keytool\f[R] command by specifying \f[V]jks\f[R] as the keystore -type. -The \f[V]cacerts\f[R] keystore file ships with a default set of root CA -certificates. -For Linux, macOS, and Windows, you can list the default certificates -with the following command: -.RS -.PP -\f[V]keytool -list -cacerts\f[R] -.RE -.PP -The initial password of the \f[V]cacerts\f[R] keystore file is -\f[V]changeit\f[R]. -System administrators should change that password and the default access -permission of that file upon installing the SDK. -.PP -\f[B]Note:\f[R] -.PP -It is important to verify your \f[V]cacerts\f[R] file. -Because you trust the CAs in the \f[V]cacerts\f[R] file as entities for -signing and issuing certificates to other entities, you must manage the -\f[V]cacerts\f[R] file carefully. -The \f[V]cacerts\f[R] file should contain only certificates of the CAs -you trust. -It is your responsibility to verify the trusted root CA certificates -bundled in the \f[V]cacerts\f[R] file and make your own trust decisions. -.PP -To remove an untrusted CA certificate from the \f[V]cacerts\f[R] file, -use the \f[V]-delete\f[R] option of the \f[V]keytool\f[R] command. -You can find the \f[V]cacerts\f[R] file in the JDK\[aq]s -\f[V]$JAVA_HOME/lib/security\f[R] directory. -Contact your system administrator if you don\[aq]t have permission to -edit this file. -.RE -.TP -Internet RFC 1421 Certificate Encoding Standard -Certificates are often stored using the printable encoding format -defined by the Internet RFC 1421 standard, instead of their binary -encoding. -This certificate format, also known as Base64 encoding, makes it easy to -export certificates to other applications by email or through some other -mechanism. -.RS -.PP -Certificates read by the \f[V]-importcert\f[R] and \f[V]-printcert\f[R] -commands can be in either this format or binary encoded. -The \f[V]-exportcert\f[R] command by default outputs a certificate in -binary encoding, but will instead output a certificate in the printable -encoding format, when the \f[V]-rfc\f[R] option is specified. -.PP -The \f[V]-list\f[R] command by default prints the SHA-256 fingerprint of -a certificate. -If the \f[V]-v\f[R] option is specified, then the certificate is printed -in human-readable format. -If the \f[V]-rfc\f[R] option is specified, then the certificate is -output in the printable encoding format. -.PP -In its printable encoding format, the encoded certificate is bounded at -the beginning and end by the following text: -.IP -.nf -\f[CB] ------BEGIN CERTIFICATE----- - -encoded certificate goes here. - ------END CERTIFICATE----- -\f[R] -.fi -.RE -.TP -X.500 Distinguished Names -X.500 Distinguished Names are used to identify entities, such as those -that are named by the \f[V]subject\f[R] and \f[V]issuer\f[R] (signer) -fields of X.509 certificates. -The \f[V]keytool\f[R] command supports the following subparts: -.RS -.IP \[bu] 2 -commonName: The common name of a person such as Susan Jones. -.IP \[bu] 2 -organizationUnit: The small organization (such as department or -division) name. -For example, Purchasing. -.IP \[bu] 2 -localityName: The locality (city) name, for example, Palo Alto. -.IP \[bu] 2 -stateName: State or province name, for example, California. -.IP \[bu] 2 -country: Two-letter country code, for example, CH. -.PP -When you supply a distinguished name string as the value of a -\f[V]-dname\f[R] option, such as for the \f[V]-genkeypair\f[R] command, -the string must be in the following format: -.RS -.PP -\f[V]CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode\f[R] -.RE -.PP -All the following items represent actual values and the previous -keywords are abbreviations for the following: -.IP -.nf -\f[CB] -CN=commonName -OU=organizationUnit -O=organizationName -L=localityName -S=stateName -C=country -\f[R] -.fi -.PP -A sample distinguished name string is: -.RS -.PP -\f[V]CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US\f[R] -.RE -.PP -A sample command using such a string is: -.RS -.PP -\f[V]keytool -genkeypair -dname \[dq]CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US\[dq] -alias mark -keyalg rsa\f[R] -.RE -.PP -Case doesn\[aq]t matter for the keyword abbreviations. -For example, CN, cn, and Cn are all treated the same. -.PP -Order matters; each subcomponent must appear in the designated order. -However, it isn\[aq]t necessary to have all the subcomponents. -You can use a subset, for example: -.RS -.PP -\f[V]CN=Smith, OU=Java, O=Oracle, C=US\f[R] -.RE -.PP -If a distinguished name string value contains a comma, then the comma -must be escaped by a backslash (\[rs]) character when you specify the -string on a command line, as in: -.RS -.PP -\f[V]cn=Jack, ou=Java\[rs], Product Development, o=Oracle, c=US\f[R] -.RE -.PP -It is never necessary to specify a distinguished name string on a -command line. -When the distinguished name is needed for a command, but not supplied on -the command line, the user is prompted for each of the subcomponents. -In this case, a comma doesn\[aq]t need to be escaped by a backslash -(\[rs]). -.RE -.SH WARNINGS -.SH IMPORTING TRUSTED CERTIFICATES WARNING -.PP -\f[B]Important\f[R]: Be sure to check a certificate very carefully -before importing it as a trusted certificate. -.PP -\f[B]Windows Example:\f[R] -.PP -View the certificate first with the \f[V]-printcert\f[R] command or the -\f[V]-importcert\f[R] command without the \f[V]-noprompt\f[R] option. -Ensure that the displayed certificate fingerprints match the expected -ones. -For example, suppose someone sends or emails you a certificate that you -put it in a file named \f[V]\[rs]tmp\[rs]cert\f[R]. -Before you consider adding the certificate to your list of trusted -certificates, you can execute a \f[V]-printcert\f[R] command to view its -fingerprints, as follows: -.IP -.nf -\f[CB] - keytool -printcert -file \[rs]tmp\[rs]cert - Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll - Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll - Serial Number: 59092b34 - Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016 - Certificate Fingerprints: - - SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE - SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90: - 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4 -\f[R] -.fi -.PP -\f[B]Linux Example:\f[R] -.PP -View the certificate first with the \f[V]-printcert\f[R] command or the -\f[V]-importcert\f[R] command without the \f[V]-noprompt\f[R] option. -Ensure that the displayed certificate fingerprints match the expected -ones. -For example, suppose someone sends or emails you a certificate that you -put it in a file named \f[V]/tmp/cert\f[R]. -Before you consider adding the certificate to your list of trusted -certificates, you can execute a \f[V]-printcert\f[R] command to view its -fingerprints, as follows: -.IP -.nf -\f[CB] - keytool -printcert -file /tmp/cert - Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll - Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll - Serial Number: 59092b34 - Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016 - Certificate Fingerprints: - - SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE - SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90: - 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4 -\f[R] -.fi -.PP -Then call or otherwise contact the person who sent the certificate and -compare the fingerprints that you see with the ones that they show. -Only when the fingerprints are equal is it guaranteed that the -certificate wasn\[aq]t replaced in transit with somebody else\[aq]s -certificate such as an attacker\[aq]s certificate. -If such an attack took place, and you didn\[aq]t check the certificate -before you imported it, then you would be trusting anything the attacker -signed, for example, a JAR file with malicious class files inside. -.PP -\f[B]Note:\f[R] -.PP -It isn\[aq]t required that you execute a \f[V]-printcert\f[R] command -before importing a certificate. -This is because before you add a certificate to the list of trusted -certificates in the keystore, the \f[V]-importcert\f[R] command prints -out the certificate information and prompts you to verify it. -You can then stop the import operation. -However, you can do this only when you call the \f[V]-importcert\f[R] -command without the \f[V]-noprompt\f[R] option. -If the \f[V]-noprompt\f[R] option is specified, then there is no -interaction with the user. -.SH PASSWORDS WARNING -.PP -Most commands that operate on a keystore require the store password. -Some commands require a private/secret key password. -Passwords can be specified on the command line in the -\f[V]-storepass\f[R] and \f[V]-keypass\f[R] options. -However, a password shouldn\[aq]t be specified on a command line or in a -script unless it is for testing, or you are on a secure system. -When you don\[aq]t specify a required password option on a command line, -you are prompted for it. -.SH CERTIFICATE CONFORMANCE WARNING -.PP -\f[B]Internet X.509 Public Key Infrastructure Certificate and -Certificate Revocation List (CRL) Profile\f[R] -[https://tools.ietf.org/rfc/rfc5280.txt] defined a profile on conforming -X.509 certificates, which includes what values and value combinations -are valid for certificate fields and extensions. -.PP -The \f[V]keytool\f[R] command doesn\[aq]t enforce all of these rules so -it can generate certificates that don\[aq]t conform to the standard, -such as self-signed certificates that would be used for internal testing -purposes. -Certificates that don\[aq]t conform to the standard might be rejected by -the JDK or other applications. -Users should ensure that they provide the correct options for -\f[V]-dname\f[R], \f[V]-ext\f[R], and so on. -.SH IMPORT A NEW TRUSTED CERTIFICATE -.PP -Before you add the certificate to the keystore, the \f[V]keytool\f[R] -command verifies it by attempting to construct a chain of trust from -that certificate to a self-signed certificate (belonging to a root CA), -using trusted certificates that are already available in the keystore. -.PP -If the \f[V]-trustcacerts\f[R] option was specified, then additional -certificates are considered for the chain of trust, namely the -certificates in a file named \f[V]cacerts\f[R]. -.PP -If the \f[V]keytool\f[R] command fails to establish a trust path from -the certificate to be imported up to a self-signed certificate (either -from the keystore or the \f[V]cacerts\f[R] file), then the certificate -information is printed, and the user is prompted to verify it by -comparing the displayed certificate fingerprints with the fingerprints -obtained from some other (trusted) source of information, which might be -the certificate owner. -Be very careful to ensure the certificate is valid before importing it -as a trusted certificate. -The user then has the option of stopping the import operation. -If the \f[V]-noprompt\f[R] option is specified, then there is no -interaction with the user. -.SH IMPORT A CERTIFICATE REPLY -.PP -When you import a certificate reply, the certificate reply is validated -with trusted certificates from the keystore, and optionally, the -certificates configured in the \f[V]cacerts\f[R] keystore file when the -\f[V]-trustcacerts\f[R] option is specified. -.PP -The methods of determining whether the certificate reply is trusted are -as follows: -.IP \[bu] 2 -If the reply is a single X.509 certificate, then the \f[V]keytool\f[R] -command attempts to establish a trust chain, starting at the certificate -reply and ending at a self-signed certificate (belonging to a root CA). -The certificate reply and the hierarchy of certificates is used to -authenticate the certificate reply from the new certificate chain of -aliases. -If a trust chain can\[aq]t be established, then the certificate reply -isn\[aq]t imported. -In this case, the \f[V]keytool\f[R] command doesn\[aq]t print the -certificate and prompt the user to verify it, because it is very -difficult for a user to determine the authenticity of the certificate -reply. -.IP \[bu] 2 -If the reply is a PKCS #7 formatted certificate chain or a sequence of -X.509 certificates, then the chain is ordered with the user certificate -first followed by zero or more CA certificates. -If the chain ends with a self-signed root CA certificate and -the\f[V]-trustcacerts\f[R] option was specified, the \f[V]keytool\f[R] -command attempts to match it with any of the trusted certificates in the -keystore or the \f[V]cacerts\f[R] keystore file. -If the chain doesn\[aq]t end with a self-signed root CA certificate and -the \f[V]-trustcacerts\f[R] option was specified, the \f[V]keytool\f[R] -command tries to find one from the trusted certificates in the keystore -or the \f[V]cacerts\f[R] keystore file and add it to the end of the -chain. -If the certificate isn\[aq]t found and the \f[V]-noprompt\f[R] option -isn\[aq]t specified, the information of the last certificate in the -chain is printed, and the user is prompted to verify it. -.PP -If the public key in the certificate reply matches the user\[aq]s public -key already stored with \f[V]alias\f[R], then the old certificate chain -is replaced with the new certificate chain in the reply. -The old chain can only be replaced with a valid \f[V]keypass\f[R], and -so the password used to protect the private key of the entry is -supplied. -If no password is provided, and the private key password is different -from the keystore password, the user is prompted for it. -.PP -This command was named \f[V]-import\f[R] in earlier releases. -This old name is still supported in this release. -The new name, \f[V]-importcert\f[R], is preferred. diff --git a/src/java.base/share/man/keytool.md b/src/java.base/share/man/keytool.md new file mode 100644 index 00000000000..22b2877a3e7 --- /dev/null +++ b/src/java.base/share/man/keytool.md @@ -0,0 +1,2430 @@ +--- +# Copyright (c) 1998, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'KEYTOOL(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +keytool - a key and certificate management utility + +## Synopsis + +`keytool` \[*commands*\] + +*commands* +: Commands for `keytool` include the following: + + - `-certreq`: Generates a certificate request + + - `-changealias`: Changes an entry's alias + + - `-delete`: Deletes an entry + + - `-exportcert`: Exports certificate + + - `-genkeypair`: Generates a key pair + + - `-genseckey`: Generates a secret key + + - `-gencert`: Generates a certificate from a certificate request + + - `-importcert`: Imports a certificate or a certificate chain + + - `-importpass`: Imports a password + + - `-importkeystore`: Imports one or all entries from another keystore + + - `-keypasswd`: Changes the key password of an entry + + - `-list`: Lists entries in a keystore + + - `-printcert`: Prints the content of a certificate + + - `-printcertreq`: Prints the content of a certificate request + + - `-printcrl`: Prints the content of a Certificate Revocation List (CRL) + file + + - `-storepasswd`: Changes the store password of a keystore + + - `-showinfo`: Displays security-related information + + - `-version`: Prints the program version + + See [Commands and Options] for a description of these commands with their + options. + +## Description + +The `keytool` command is a key and certificate management utility. It enables +users to administer their own public/private key pairs and associated +certificates for use in self-authentication (where a user authenticates +themselves to other users and services) or data integrity and authentication +services, by using digital signatures. The `keytool` command also enables users +to cache the public keys (in the form of certificates) of their communicating +peers. + +A certificate is a digitally signed statement from one entity (person, company, +and so on), which says that the public key (and some other information) of some +other entity has a particular value. When data is digitally signed, the +signature can be verified to check the data integrity and authenticity. +Integrity means that the data hasn't been modified or tampered with, and +authenticity means that the data comes from the individual who claims to have +created and signed it. + +The `keytool` command also enables users to administer secret keys and +passphrases used in symmetric encryption and decryption (Data Encryption +Standard). It can also display other security-related information. + +The `keytool` command stores the keys and certificates in a keystore. + +The `keytool` command uses the `jdk.certpath.disabledAlgorithms` and +`jdk.security.legacyAlgorithms` security properties to determine which +algorithms are considered a security risk. It emits warnings when +disabled or legacy algorithms are being used. +The `jdk.certpath.disabledAlgorithms` and `jdk.security.legacyAlgorithms` +security properties are defined in the `java.security` file (located in +the JDK's `$JAVA_HOME/conf/security` directory). + +## Command and Option Notes + +The following notes apply to the descriptions in [Commands and Options]\: + +- All command and option names are preceded by a hyphen sign (`-`). + +- Only one command can be provided. + +- Options for each command can be provided in any order. + +- There are two kinds of options, one is single-valued which should be + only provided once. If a single-valued option is provided multiple times, + the value of the last one is used. The other type is multi-valued, + which can be provided multiple times and all values are used. + The only multi-valued option currently supported is the `-ext` option used + to generate X.509v3 certificate extensions. + +- All items not italicized or in braces ({ }) or brackets (\[ \]) are + required to appear as is. + +- Braces surrounding an option signify that a default value is used when the + option isn't specified on the command line. Braces are also used around the + `-v`, `-rfc`, and `-J` options, which have meaning only when they appear on + the command line. They don't have any default values. + +- Brackets surrounding an option signify that the user is prompted for the + values when the option isn't specified on the command line. For the + `-keypass` option, if you don't specify the option on the command line, + then the `keytool` command first attempts to use the keystore password to + recover the private/secret key. If this attempt fails, then the `keytool` + command prompts you for the private/secret key password. + +- Items in italics (option values) represent the actual values that must be + supplied. For example, here is the format of the `-printcert` command: + + > `keytool -printcert` {`-file` *cert\_file*} {`-v`} + + When you specify a `-printcert` command, replace *cert\_file* with the + actual file name, as follows: `keytool -printcert -file VScert.cer` + +- Option values must be enclosed in quotation marks when they contain a blank + (space). + +## Commands and Options + +The keytool commands and their options can be grouped by the tasks that they +perform. + +[Commands for Creating or Adding Data to the Keystore]\: + +- `-gencert` + +- `-genkeypair` + +- `-genseckey` + +- `-importcert` + +- `-importpass` + +[Commands for Importing Contents from Another Keystore]\: + +- `-importkeystore` + +[Commands for Generating a Certificate Request]\: + +- `-certreq` + +[Commands for Exporting Data]\: + +- `-exportcert` + +[Commands for Displaying Data]\: + +- `-list` + +- `-printcert` + +- `-printcertreq` + +- `-printcrl` + +[Commands for Managing the Keystore]\: + +- `-storepasswd` + +- `-keypasswd` + +- `-delete` + +- `-changealias` + +[Commands for Displaying Security-related Information]\: + +- `-showinfo` + +[Commands for Displaying Program Version]\: + +- `-version` + +## Commands for Creating or Adding Data to the Keystore + +`-gencert` +: The following are the available options for the `-gencert` command: + + - {`-rfc`}: Output in RFC (Request For Comment) style + + - {`-infile` *infile*}: Input file name + + - {`-outfile` *outfile*}: Output file name + + - {`-alias` *alias*}: Alias name of the entry to process + + - {`-sigalg` *sigalg*}: Signature algorithm name + + - {`-dname` *dname*}: Distinguished name + + - {`-startdate` *startdate*}: Certificate validity start date and time + + - {`-ext` *ext*}\*: X.509 extension + + - {`-validity` *days*}: Validity number of days + + - \[`-keypass` *arg*\]: Key password + + - {`-keystore` *keystore*}: Keystore name + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Adds a security + provider by name (such as SunPKCS11) with an optional configure + argument. The value of the security provider is the name of a security + provider that is defined in a module. + + For example, + + > `keytool -addprovider SunPKCS11 -providerarg some.cfg ...` + + **Note:** + + For compatibility reasons, the SunPKCS11 provider can still be loaded + with `-providerclass sun.security.pkcs11.SunPKCS11` even if it is now + defined in a module. This is the only module included in the JDK that + needs a configuration, and therefore the most widely used with the + `-providerclass` option. For legacy security providers located on + classpath and loaded by reflection, `-providerclass` should still be + used. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + For example, if `MyProvider` is a legacy provider loaded via + reflection, + + > `keytool -providerclass com.example.MyProvider ...` + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-gencert` command to generate a certificate as a response to a + certificate request file (which can be created by the `keytool -certreq` + command). The command reads the request either from *infile* or, if + omitted, from the standard input, signs it by using the alias's private + key, and outputs the X.509 certificate into either *outfile* or, if + omitted, to the standard output. When `-rfc` is specified, the output + format is Base64-encoded PEM; otherwise, a binary DER is created. + + The `-sigalg` value specifies the algorithm that should be used to sign the + certificate. The *startdate* argument is the start time and date that the + certificate is valid. The *days* argument tells the number of days for + which the certificate should be considered valid. + + When *dname* is provided, it is used as the subject of the generated + certificate. Otherwise, the one from the certificate request is used. + + The `-ext` value shows what X.509 extensions will be embedded in the + certificate. Read [Common Command Options] for the grammar of `-ext`. + + The `-gencert` option enables you to create certificate chains. The + following example creates a certificate, `e1`, that contains three + certificates in its certificate chain. + + The following commands creates four key pairs named `ca`, `ca1`, `ca2`, and + `e1`: + + ``` + keytool -alias ca -dname CN=CA -genkeypair -keyalg rsa + keytool -alias ca1 -dname CN=CA -genkeypair -keyalg rsa + keytool -alias ca2 -dname CN=CA -genkeypair -keyalg rsa + keytool -alias e1 -dname CN=E1 -genkeypair -keyalg rsa + ``` + + The following two commands create a chain of signed certificates; `ca` + signs `ca1` and `ca1` signs `ca2`, all of which are self-issued: + + ``` + keytool -alias ca1 -certreq | + keytool -alias ca -gencert -ext san=dns:ca1 | + keytool -alias ca1 -importcert + + keytool -alias ca2 -certreq | + keytool -alias ca1 -gencert -ext san=dns:ca2 | + keytool -alias ca2 -importcert + ``` + + The following command creates the certificate `e1` and stores it in the + `e1.cert` file, which is signed by `ca2`. As a result, `e1` should contain + `ca`, `ca1`, and `ca2` in its certificate chain: + + > `keytool -alias e1 -certreq | keytool -alias ca2 -gencert > e1.cert` + +`-genkeypair` +: The following are the available options for the `-genkeypair` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - `-keyalg` *alg*: Key algorithm name + + - {`-keysize` *size*}: Key bit size + + - {`-groupname` *name*}: Group name. For example, an Elliptic Curve name. + + - {`-sigalg` *alg*}: Signature algorithm name + + - {`-signer` *alias*}: Signer alias + + - \[`-signerkeypass` *arg*\]: Signer key password + + - \[`-dname` *name*\]: Distinguished name + + - {`-startdate` *date*}: Certificate validity start date and time + + - {`-ext` *value*}\*: X.509 extension + + - {`-validity` *days*}: Validity number of days + + - \[`-keypass` *arg*\]: Key password + + - {`-keystore` *keystore*}: Keystore name + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\] }: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-genkeypair` command to generate a key pair (a public key and + associated private key). When the `-signer` option is not specified, + the public key is wrapped in an X.509 v3 self-signed certificate and + stored as a single-element certificate chain. When the `-signer` + option is specified, a new certificate is generated and signed by + the designated signer and stored as a multiple-element certificate + chain (containing the generated certificate itself, and the signer's + certificate chain). The certificate chain and private key are stored + in a new keystore entry that is identified by its alias. + + The `-keyalg` value specifies the algorithm to be used to generate the key + pair. The `-keysize` value specifies the size of each key to be generated. + The `-groupname` value specifies the named group (for example, the standard + or predefined name of an Elliptic Curve) of the key to be generated. + + When a `-keysize` value is provided, it will be used to initialize a + `KeyPairGenerator` object using the `initialize(int keysize)` + method. When a `-groupname` value is provided, it will be used to + initialize a `KeyPairGenerator` object using the + `initialize(AlgorithmParameterSpec params)` method where `params` + is `new NamedParameterSpec(groupname)`. + + Only one of `-groupname` and `-keysize` can be specified. If an algorithm + has multiple named groups that have the same key size, the `-groupname` + option should usually be used. In this case, if `-keysize` is specified, + it's up to the security provider to determine which named group is chosen + when generating a key pair. + + The `-sigalg` value specifies the algorithm that should be used + to sign the certificate. This algorithm must be compatible with + the `-keyalg` value. + + The `-signer` value specifies the alias of a `PrivateKeyEntry` for the + signer that already exists in the keystore. This option is used to + sign the certificate with the signer's private key. This is especially + useful for key agreement algorithms (i.e. the `-keyalg` value is `XDH`, + `X25519`, `X448`, or `DH`) as these keys cannot be used for digital + signatures, and therefore a self-signed certificate cannot be created. + + The `-signerkeypass` value specifies the password of the signer's private + key. It can be specified if the private key of the signer entry is + protected by a password different from the store password. + + The `-dname` value specifies the X.500 Distinguished Name to be associated + with the value of `-alias`. If the `-signer` option is not specified, the + issuer and subject fields of the self-signed certificate are populated + with the specified distinguished name. If the `-signer` option is + specified, the subject field of the certificate is populated with the + specified distinguished name and the issuer field is populated with the + subject field of the signer's certificate. If a distinguished name is not + provided at the command line, then the user is prompted for one. + + The value of `-keypass` is a password used to protect the private key of + the generated key pair. If a password is not provided, then the user is + prompted for it. If you press the **Return** key at the prompt, then the + key password is set to the same password as the keystore password. The + `-keypass` value must have at least six characters. + + The value of `-startdate` specifies the issue time of the certificate, also + known as the "Not Before" value of the X.509 certificate's Validity field. + + The option value can be set in one of these two forms: + + (\[`+-`\]*nnn*\[`ymdHMS`\])+ + + \[*yyyy*`/`*mm*`/`*dd*\] \[*HH*`:`*MM*`:`*SS*\] + + With the first form, the issue time is shifted by the specified value from + the current time. The value is a concatenation of a sequence of subvalues. + Inside each subvalue, the plus sign (+) means shift forward, and the minus + sign (-) means shift backward. The time to be shifted is *nnn* units of + years, months, days, hours, minutes, or seconds (denoted by a single + character of `y`, `m`, `d`, `H`, `M`, or `S` respectively). The exact value + of the issue time is calculated by using the + `java.util.GregorianCalendar.add(int field, int amount)` method on each + subvalue, from left to right. For example, the issue time can be specified + by: + + ``` + Calendar c = new GregorianCalendar(); + c.add(Calendar.YEAR, -1); + c.add(Calendar.MONTH, 1); + c.add(Calendar.DATE, -1); + return c.getTime() + ``` + + With the second form, the user sets the exact issue time in two parts, + year/month/day and hour:minute:second (using the local time zone). The user + can provide only one part, which means the other part is the same as the + current date (or time). The user must provide the exact number of digits + shown in the format definition (padding with 0 when shorter). When both + date and time are provided, there is one (and only one) space character + between the two parts. The hour should always be provided in 24-hour + format. + + When the option isn't provided, the start date is the current time. The + option can only be provided one time. + + The value of *date* specifies the number of days (starting at the date + specified by `-startdate`, or the current date when `-startdate` isn't + specified) for which the certificate should be considered valid. + +`-genseckey` +: The following are the available options for the `-genseckey` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - \[`-keypass` *arg*\]: Key password + + - `-keyalg` *alg*: Key algorithm name + + - {`-keysize` *size*}: Key bit size + + - {`-keystore` *keystore*}: Keystore name + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-genseckey` command to generate a secret key and store it in a new + `KeyStore.SecretKeyEntry` identified by `alias`. + + The value of `-keyalg` specifies the algorithm to be used to generate the + secret key, and the value of `-keysize` specifies the size of the key that + is generated. The `-keypass` value is a password that protects the secret + key. If a password is not provided, then the user is prompted for it. If + you press the **Return** key at the prompt, then the key password is set to + the same password that is used for the `-keystore`. The `-keypass` value + must contain at least six characters. + +`-importcert` +: The following are the available options for the `-importcert` command: + + - {`-noprompt`}: Do not prompt + + - {`-trustcacerts`}: Trust certificates from cacerts + + - {`-protected`}: Password is provided through protected mechanism + + - {`-alias` *alias*}: Alias name of the entry to process + + - {`-file` *file*}: Input file name + + - \[`-keypass` *arg*\]: Key password + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + Use the `-importcert` command to read the certificate or certificate chain + (where the latter is supplied in a PKCS\#7 formatted reply or in a sequence + of X.509 certificates) from `-file` *file*, and store it in the `keystore` + entry identified by `-alias`. If `-file` *file* is not specified, then the + certificate or certificate chain is read from `stdin`. + + The `keytool` command can import X.509 v1, v2, and v3 certificates, and + PKCS\#7 formatted certificate chains consisting of certificates of that + type. The data to be imported must be provided either in binary encoding + format or in printable encoding format (also known as Base64 encoding) as + defined by the Internet RFC 1421 standard. In the latter case, the encoding + must be bounded at the beginning by a string that starts with `-----BEGIN`, + and bounded at the end by a string that starts with `-----END`. + + You import a certificate for two reasons: To add it to the list of trusted + certificates, and to import a certificate reply received from a certificate + authority (CA) as the result of submitting a Certificate Signing Request + (CSR) to that CA. See the `-certreq` command in [Commands for Generating a + Certificate Request]. + + The type of import is indicated by the value of the `-alias` option. If the + alias doesn't point to a key entry, then the `keytool` command assumes you + are adding a trusted certificate entry. In this case, the alias shouldn't + already exist in the keystore. If the alias does exist, then the `keytool` + command outputs an error because a trusted certificate already exists for + that alias, and doesn't import the certificate. If `-alias` points to a key + entry, then the `keytool` command assumes that you're importing a + certificate reply. + +`-importpass` +: The following are the available options for the `-importpass` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - \[`-keypass` *arg*\]: Key password + + - {`-keyalg` *alg*}: Key algorithm name + + - {`-keysize` *size*}: Key bit size + + - {`-keystore` *keystore*}: Keystore name + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-importpass` command to imports a passphrase and store it in a new + `KeyStore.SecretKeyEntry` identified by `-alias`. The passphrase may be + supplied via the standard input stream; otherwise the user is prompted for + it. The `-keypass` option provides a password to protect the imported + passphrase. If a password is not provided, then the user is prompted for + it. If you press the **Return** key at the prompt, then the key password is + set to the same password as that used for the `keystore`. The `-keypass` + value must contain at least six characters. + +## Commands for Importing Contents from Another Keystore + +`-importkeystore` +: The following are the available options for the `-importkeystore` command: + + - `-srckeystore` *keystore*: Source keystore name + + - {`-destkeystore` *keystore*}: Destination keystore name + + - {`-srcstoretype` *type*}: Source keystore type + + - {`-deststoretype` *type*}: Destination keystore type + + - \[`-srcstorepass` *arg*\]: Source keystore password + + - \[`-deststorepass` *arg*\]: Destination keystore password + + - {`-srcprotected`}: Source keystore password protected + + - {`-destprotected`}: Destination keystore password protected + + - {`-srcprovidername` *name*}: Source keystore provider name + + - {`-destprovidername` *name*}: Destination keystore provider name + + - {`-srcalias` *alias*}: Source alias + + - {`-destalias` *alias*}: Destination alias + + - \[`-srckeypass` *arg*\]: Source key password + + - \[`-destkeypass` *arg*\]: Destination key password + + - {`-noprompt`}: Do not prompt + + - {`-addprovider` *name* \[`-providerarg` *arg*\]: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + **Note:** + + This is the first line of all options: + + > `-srckeystore` *keystore* `-destkeystore` *keystore* + + Use the `-importkeystore` command to import a single entry or all entries + from a source keystore to a destination keystore. + + **Note:** + + If you do not specify `-destkeystore` when using the + `keytool -importkeystore` command, then the default keystore used is + `$HOME/.keystore`. + + When the `-srcalias` option is provided, the command imports the single + entry identified by the alias to the destination keystore. If a destination + alias isn't provided with `-destalias`, then `-srcalias` is used as the + destination alias. If the source entry is protected by a password, then + `-srckeypass` is used to recover the entry. If `-srckeypass` isn't + provided, then the `keytool` command attempts to use `-srcstorepass` to + recover the entry. If `-srcstorepass` is not provided or is incorrect, then + the user is prompted for a password. The destination entry is protected + with `-destkeypass`. If `-destkeypass` isn't provided, then the destination + entry is protected with the source entry password. For example, most + third-party tools require `storepass` and `keypass` in a PKCS \#12 keystore + to be the same. To create a PKCS\#12 keystore for these tools, always + specify a `-destkeypass` that is the same as `-deststorepass`. + + If the `-srcalias` option isn't provided, then all entries in the source + keystore are imported into the destination keystore. Each destination entry + is stored under the alias from the source entry. If the source entry is + protected by a password, then `-srcstorepass` is used to recover the entry. + If `-srcstorepass` is not provided or is incorrect, then the user is + prompted for a password. If a source keystore entry type isn't supported in + the destination keystore, or if an error occurs while storing an entry into + the destination keystore, then the user is prompted either to skip the + entry and continue or to quit. The destination entry is protected with the + source entry password. + + If the destination alias already exists in the destination keystore, then + the user is prompted either to overwrite the entry or to create a new entry + under a different alias name. + + If the `-noprompt` option is provided, then the user isn't prompted for a + new destination alias. Existing entries are overwritten with the + destination alias name. Entries that can't be imported are skipped and a + warning is displayed. + +## Commands for Generating a Certificate Request + +`-certreq` +: The following are the available options for the `-certreq` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - {`-sigalg` *alg*}: Signature algorithm name + + - {`-file` *file*}: Output file name + + - \[ `-keypass` *arg*\]: Key password + + - {`-keystore` *keystore*}: Keystore name + + - {`-dname` *name*}: Distinguished name + + - {`-ext` *value*}: X.509 extension + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-certreq` command to generate a Certificate Signing Request (CSR) + using the PKCS \#10 format. + + A CSR is intended to be sent to a CA. The CA authenticates the certificate + requestor (usually offline) and returns a certificate or certificate chain + to replace the existing certificate chain (initially a self-signed + certificate) in the keystore. + + The private key associated with *alias* is used to create the PKCS \#10 + certificate request. To access the private key, the correct password must + be provided. If `-keypass` isn't provided at the command line and is + different from the password used to protect the integrity of the keystore, + then the user is prompted for it. If `-dname` is provided, then it is used + as the subject in the CSR. Otherwise, the X.500 Distinguished Name + associated with alias is used. + + The `-sigalg` value specifies the algorithm that should be used to sign the + CSR. + + The CSR is stored in the `-file` *file*. If a file is not specified, then + the CSR is output to `-stdout`. + + Use the `-importcert` command to import the response from the CA. + +## Commands for Exporting Data + +`-exportcert` +: The following are the available options for the `-exportcert` command: + + - {`-rfc`}: Output in RFC style + + - {`-alias` *alias*}: Alias name of the entry to process + + - {`-file` *file*}: Output file name + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\] }: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-exportcert` command to read a certificate from the keystore that + is associated with `-alias` *alias* and store it in the `-file` *file*. + When a file is not specified, the certificate is output to `stdout`. + + By default, the certificate is output in binary encoding. If the `-rfc` + option is specified, then the output in the printable encoding format + defined by the Internet RFC 1421 Certificate Encoding Standard. + + If `-alias` refers to a trusted certificate, then that certificate is + output. Otherwise, `-alias` refers to a key entry with an associated + certificate chain. In that case, the first certificate in the chain is + returned. This certificate authenticates the public key of the entity + addressed by `-alias`. + +## Commands for Displaying Data + +`-list` +: The following are the available options for the `-list` command: + + - {`-rfc`}: Output in RFC style + + - {`-alias` *alias*}: Alias name of the entry to process + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\] }: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-list` command to print the contents of the keystore entry + identified by `-alias` to `stdout`. If `-alias` *alias* is not specified, + then the contents of the entire keystore are printed. + + By default, this command prints the SHA-256 fingerprint of a certificate. + If the `-v` option is specified, then the certificate is printed in + human-readable format, with additional information such as the owner, + issuer, serial number, and any extensions. If the `-rfc` option is + specified, then the certificate contents are printed by using the printable + encoding format, as defined by the Internet RFC 1421 Certificate Encoding + Standard. + + **Note:** + + You can't specify both `-v` and `-rfc` in the same command. Otherwise, an + error is reported. + +`-printcert` +: The following are the available options for the `-printcert` command: + + - {`-rfc`}: Output in RFC style + + - {`-file` *cert\_file*}: Input file name + + - {`-sslserver` *server*\[`:`*port*\]}:: Secure Sockets Layer (SSL) + server host and port + + - {`-jarfile` *JAR\_file*}: Signed `.jar` file + + - {`-keystore` *keystore*}: Keystore name + + - {`-trustcacerts`}: Trust certificates from cacerts + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-protected`}: Password is provided through protected mechanism + + - {`-v`}: Verbose output + + Use the `-printcert` command to read and print the certificate from `-file` + *cert\_file*, the SSL server located at `-sslserver` *server*\[`:`*port*\], + or the signed JAR file specified by `-jarfile` *JAR\_file*. It prints its + contents in a human-readable format. When a port is not specified, the + standard HTTPS port 443 is assumed. + + **Note:** + + The `-sslserver` and `-file` options can't be provided in the same command. + Otherwise, an error is reported. If you don't specify either option, then + the certificate is read from `stdin`. + + When`-rfc` is specified, the `keytool` command prints the certificate in + PEM mode as defined by the Internet RFC 1421 Certificate Encoding standard. + + If the certificate is read from a file or `stdin`, then it might be either + binary encoded or in printable encoding format, as defined by the RFC 1421 + Certificate Encoding standard. + + If the SSL server is behind a firewall, then the + `-J-Dhttps.proxyHost=proxyhost` and `-J-Dhttps.proxyPort=proxyport` options + can be specified on the command line for proxy tunneling. + + **Note:** + + This command can be used independently of a keystore. This command does not + check for the weakness of a certificate's signature algorithm if it is a + trusted certificate in the user keystore (specified by `-keystore`) or in + the `cacerts` keystore (if `-trustcacerts` is specified). + +`-printcertreq` +: The following are the available options for the `-printcertreq` command: + + - {`-file` *file*}: Input file name + + - {`-v`}: Verbose output + + Use the `-printcertreq` command to print the contents of a PKCS \#10 format + certificate request, which can be generated by the `keytool -certreq` + command. The command reads the request from file. If there is no file, then + the request is read from the standard input. + +`-printcrl` +: The following are the available options for the `-printcrl` command: + + - {`-file crl`}: Input file name + + - {`-keystore` *keystore*}: Keystore name + + - {`-trustcacerts`}: Trust certificates from cacerts + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-protected`}: Password is provided through protected mechanism + + - {`-v`}: Verbose output + + Use the `-printcrl` command to read the Certificate Revocation List (CRL) + from `-file crl` . A CRL is a list of the digital certificates that were + revoked by the CA that issued them. The CA generates the `crl` file. + + **Note:** + + This command can be used independently of a keystore. This command attempts + to verify the CRL using a certificate from the user keystore (specified by + `-keystore`) or the `cacerts` keystore (if `-trustcacerts` is specified), and + will print out a warning if it cannot be verified. + +## Commands for Managing the Keystore + +`-storepasswd` +: The following are the available options for the `-storepasswd` command: + + - \[`-new` *arg*\]: New password + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + Use the `-storepasswd` command to change the password used to protect the + integrity of the keystore contents. The new password is set by `-new` *arg* + and must contain at least six characters. + +`-keypasswd` +: The following are the available options for the `-keypasswd` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - \[`-keypass` *old\_keypass*\]: Key password + + - \[`-new` *new\_keypass*\]: New password + + - {`-keystore` *keystore*}: Keystore name + + - {`-storepass` *arg*}: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + Use the `-keypasswd` command to change the password (under which + private/secret keys identified by `-alias` are protected) from `-keypass` + *old\_keypass* to `-new` *new\_keypass*. The password value must contain at + least six characters. + + If the `-keypass` option isn't provided at the command line and the + `-keypass` password is different from the keystore password (`-storepass` + *arg*), then the user is prompted for it. + + If the `-new` option isn't provided at the command line, then the user is + prompted for it. + +`-delete` +: The following are the available options for the `-delete` command: + + - \[`-alias` *alias*\]: Alias name of the entry to process + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-delete` command to delete the `-alias` *alias* entry from the + keystore. When not provided at the command line, the user is prompted for + the `alias`. + +`-changealias` +: The following are the available options for the `-changealias` command: + + - {`-alias` *alias*}: Alias name of the entry to process + + - \[`-destalias` *alias*\]: Destination alias + + - \[`-keypass` *arg*\]: Key password + + - {`-keystore` *keystore*}: Keystore name + + - {`-cacerts`}: Access the cacerts keystore + + - \[`-storepass` *arg*\]: Keystore password + + - {`-storetype` *type*}: Keystore type + + - {`-providername` *name*}: Provider name + + - {`-addprovider` *name* \[`-providerarg` *arg*\]}: Add security provider + by name (such as SunPKCS11) with an optional configure argument. + + - {`-providerclass` *class* \[`-providerarg` *arg*\]}: Add security + provider by fully qualified class name with an optional configure + argument. + + - {`-providerpath` *list*}: Provider classpath + + - {`-v`}: Verbose output + + - {`-protected`}: Password provided through a protected mechanism + + Use the `-changealias` command to move an existing keystore entry from + `-alias` *alias* to a new `-destalias` *alias*. If a destination alias is + not provided, then the command prompts you for one. If the original entry + is protected with an entry password, then the password can be supplied with + the `-keypass` option. If a key password is not provided, then the + `-storepass` (if provided) is attempted first. If the attempt fails, then + the user is prompted for a password. + +## Commands for Displaying Security-related Information + +`-showinfo` +: The following are the available options for the `-showinfo` command: + + - {`-tls`}: Displays TLS configuration information + + - {`-v`}: Verbose output + + Use the `-showinfo` command to display various security-related + information. The `-tls` option displays TLS configurations, such as + the list of enabled protocols and cipher suites. + +## Commands for Displaying Program Version + +You can use `-version` to print the program version of `keytool`. + +## Commands for Displaying Help Information + +You can use `--help` to display a list of `keytool` commands or to display help +information about a specific `keytool` command. + +- To display a list of `keytool` commands, enter: + + > `keytool --help` + +- To display help information about a specific `keytool` command, enter: + + > `keytool - --help` + +## Common Command Options + +The `-v` option can appear for all commands except `--help`. When the `-v` +option appears, it signifies verbose mode, which means that more information is +provided in the output. + +The `-J`*option* argument can appear for any command. When the `-J`*option* is +used, the specified *option* string is passed directly to the Java interpreter. +This option doesn't contain any spaces. It's useful for adjusting the execution +environment or memory usage. For a list of possible interpreter options, enter +`java -h` or `java -X` at the command line. + +These options can appear for all commands operating on a keystore: + +`-storetype` *storetype* +: This qualifier specifies the type of keystore to be instantiated. + +`-keystore` *keystore* +: The keystore location. + + If the JKS `storetype` is used and a keystore file doesn't yet exist, then + certain `keytool` commands can result in a new keystore file being created. + For example, if `keytool -genkeypair` is called and the `-keystore` option + isn't specified, the default keystore file named `.keystore` is created in + the user's home directory if it doesn't already exist. Similarly, if the + `-keystore ks_file` option is specified but `ks_file` doesn't exist, then + it is created. For more information on the JKS `storetype`, see the + **KeyStore Implementation** section in **KeyStore aliases**. + + Note that the input stream from the `-keystore` option is passed to the + `KeyStore.load` method. If `NONE` is specified as the URL, then a null + stream is passed to the `KeyStore.load` method. `NONE` should be specified + if the keystore isn't file-based. For example, when the keystore resides on + a hardware token device. + +`-cacerts` *cacerts* +: Operates on the *cacerts* keystore . This option is equivalent to + `-keystore` *path\_to\_cacerts* `-storetype` *type\_of\_cacerts*. An error + is reported if the `-keystore` or `-storetype` option is used with the + `-cacerts` option. + +`-storepass` \[`:env` \| `:file` \] *argument* +: The password that is used to protect the integrity of the keystore. + + If the modifier `env` or `file` isn't specified, then the password has the + value *argument*, which must contain at least six characters. Otherwise, + the password is retrieved as follows: + + - `env`: Retrieve the password from the environment variable named + *argument*. + + - `file`: Retrieve the password from the file named *argument*. + + **Note:** All other options that require passwords, such as `-keypass`, + `-srckeypass`, `-destkeypass`, `-srcstorepass`, and `-deststorepass`, + accept the `env` and `file` modifiers. Remember to separate the password + option and the modifier with a colon (:). + + The password must be provided to all commands that access the keystore + contents. For such commands, when the `-storepass` option isn't provided at + the command line, the user is prompted for it. + + When retrieving information from the keystore, the password is optional. If + a password is not specified, then the integrity of the retrieved + information can't be verified and a warning is displayed. + +`-providername` *name* +: Used to identify a cryptographic service provider's name when listed in the + security properties file. + +`-addprovider` *name* +: Used to add a security provider by name (such as SunPKCS11) . + +`-providerclass` *class* +: Used to specify the name of a cryptographic service provider's master class + file when the service provider isn't listed in the security properties + file. + +`-providerpath` *list* +: Used to specify the provider classpath. + +`-providerarg` *arg* +: Used with the `-addprovider` or `-providerclass` option to represent an + optional string input argument for the constructor of *class* name. + +`-protected=true`\|`false` +: Specify this value as `true` when a password must be specified by way of a + protected authentication path, such as a dedicated PIN reader. Because + there are two keystores involved in the `-importkeystore` command, the + following two options, `-srcprotected` and `-destprotected`, are provided + for the source keystore and the destination keystore respectively. + +`-ext` {*name*{`:critical`} {`=`*value*}} +: Denotes an X.509 certificate extension. The option can be used in + `-genkeypair` and `-gencert` to embed extensions into the generated + certificate, or in `-certreq` to show what extensions are requested in the + certificate request. The option can appear multiple times. The *name* + argument can be a supported extension name (see [Supported Named + Extensions]) or an arbitrary OID number. The *value* argument, when + provided, denotes the argument for the extension. When *value* is omitted, + the default value of the extension or the extension itself requires no + argument. The `:critical` modifier, when provided, means the extension's + `isCritical` attribute is `true`; otherwise, it is `false`. You can use + `:c` in place of `:critical`. + +`-conf` *file* +: Specifies a pre-configured options file. + +## Pre-configured options file + +A pre-configured options file is a Java properties file that can be specified +with the `-conf` option. Each property represents the default option(s) for +a keytool command using "keytool.*command_name*" as the property name. A +special property named "keytool.all" represents the default option(s) applied +to all commands. A property value can include `${prop}` which will be expanded +to the system property associated with it. If an option value includes white +spaces inside, it should be surrounded by quotation marks (" or '). All +property names must be in lower case. + +When `keytool` is launched with a pre-configured options file, the value for +"keytool.all" (if it exists) is prepended to the `keytool` command line first, +with the value for the command name (if it exists) comes next, and the existing +options on the command line at last. For a single-valued option, this allows +the property for a specific command to override the "keytool.all" value, +and the value specified on the command line to override both. For +multiple-valued options, all of them will be used by `keytool`. + +For example, given the following file named `preconfig`: +``` + # A tiny pre-configured options file + keytool.all = -keystore ${user.home}/ks + keytool.list = -v + keytool.genkeypair = -keyalg rsa +``` + +`keytool -conf preconfig -list` is identical to + +> `keytool -keystore ~/ks -v -list` + +`keytool -conf preconfig -genkeypair -alias me` is identical to + +> `keytool -keystore ~/ks -keyalg rsa -genkeypair -alias me` + +`keytool -conf preconfig -genkeypair -alias you -keyalg ec` is identical to + +> `keytool -keystore ~/ks -keyalg rsa -genkeypair -alias you -keyalg ec` + +which is equivalent to + +> `keytool -keystore ~/ks -genkeypair -alias you -keyalg ec` + +because `-keyalg` is a single-valued option and the `ec` value specified +on the command line overrides the preconfigured options file. + +## Examples of Option Values + +The following examples show the defaults for various option values: + +``` +-alias "mykey" + +-keysize + 2048 (when using -genkeypair and -keyalg is "DSA") + 3072 (when using -genkeypair and -keyalg is "RSA", "RSASSA-PSS", or "DH") + 384 (when using -genkeypair and -keyalg is "EC") + 56 (when using -genseckey and -keyalg is "DES") + 168 (when using -genseckey and -keyalg is "DESede") + +-groupname + ed25519 (when using -genkeypair and -keyalg is "EdDSA", key size is 255) + x25519 (when using -genkeypair and -keyalg is "XDH", key size is 255) + +-validity 90 + +-keystore + +-destkeystore + +-storetype + +-file + stdin (if reading) + stdout (if writing) + +-protected false +``` + +When generating a certificate or a certificate request, the default signature +algorithm (`-sigalg` option) is derived from the algorithm of the underlying +private key to provide an appropriate level of security strength as follows: + +Table: Default Signature Algorithms + +keyalg key size default sigalg +------- -------- -------------- +DSA any size SHA256withDSA +RSA \< 624 SHA256withRSA (key size is too small for using SHA-384) + \<= 7680 SHA384withRSA + \> 7680 SHA512withRSA +EC \< 512 SHA384withECDSA + \>= 512 SHA512withECDSA +RSASSA-PSS \< 624 RSASSA-PSS (with SHA-256, key size is too small for + using SHA-384) + \<= 7680 RSASSA-PSS (with SHA-384) + \> 7680 RSASSA-PSS (with SHA-512) +EdDSA 255 Ed25519 + 448 Ed448 +Ed25519 255 Ed25519 +Ed448 448 Ed448 +------- -------- -------------- + +* The key size, measured in bits, corresponds to the size of the private key. +This size is determined by the value of the `-keysize` or `-groupname` options +or the value derived from a default setting. + +* An RSASSA-PSS signature algorithm uses a `MessageDigest` +algorithm as its hash and MGF1 algorithms. + +* If neither a default `-keysize` or `-groupname` is defined for an algorithm, +the security provider will choose a default setting. + +**Note:** + +To improve out of the box security, default keysize, groupname, and signature +algorithm names are periodically updated to stronger values with each release +of the JDK. If interoperability with older releases of the JDK is important, +make sure that the defaults are supported by those releases. Alternatively, +you can use the `-keysize`, `-groupname`, or `-sigalg` options to override +the default values at your own risk. + +## Supported Named Extensions + +The `keytool` command supports these named extensions. The names aren't +case-sensitive. + +`BC` or `BasicConstraints` +: Values: + + The full form is `ca:`{`true`\|`false`}\[`,pathlen:`*len*\] or *len*, which + is short for `ca:true,pathlen:`*len*. + + When *len* is omitted, the resulting value is `ca:true`. + +`KU` or `KeyUsage` +: Values: + + *usage*(`,` *usage*)\* + + *usage* can be one of the following: + + - `digitalSignature` + + - `nonRepudiation` (`contentCommitment`) + + - `keyEncipherment` + + - `dataEncipherment` + + - `keyAgreement` + + - `keyCertSign` + + - `cRLSign` + + - `encipherOnly` + + - `decipherOnly` + + Provided there is no ambiguity, the *usage* argument can be abbreviated + with the first few letters (such as `dig` for `digitalSignature`) or in + camel-case style (such as `dS` for `digitalSignature` or `cRLS` for + `cRLSign`). The *usage* values are case-sensitive. + +`EKU` or `ExtendedKeyUsage` +: Values: + + *usage*(`,` *usage*)\* + + *usage* can be one of the following: + + - `anyExtendedKeyUsage` + + - `serverAuth` + + - `clientAuth` + + - `codeSigning` + + - `emailProtection` + + - `timeStamping` + + - `OCSPSigning` + + - Any OID string + + Provided there is no ambiguity, the *usage* argument can be abbreviated + with the first few letters or in camel-case style. The *usage* values are + case-sensitive. + +`SAN` or `SubjectAlternativeName` +: Values: + + *type*`:`*value*(`,` *type*`:`*value*)\* + + *type* can be one of the following: + + - `EMAIL` + + - `URI` + + - `DNS` + + - `IP` + + - `OID` + + The *value* argument is the string format value for the *type*. + +`IAN` or `IssuerAlternativeName` +: Values: + + Same as `SAN` or `SubjectAlternativeName`. + +`SIA` or `SubjectInfoAccess` +: Values: + + *method*`:`*location-type*`:`*location-value*(`,` + *method*`:`*location-type*`:`*location-value*)\* + + *method* can be one of the following: + + - `timeStamping` + + - `caRepository` + + - Any OID + + The *location-type* and *location-value* arguments can be any + *type*`:`*value* supported by the `SubjectAlternativeName` extension. + +`AIA` or `AuthorityInfoAccess` +: Values: + + Same as `SIA` or `SubjectInfoAccess`. + + The *method* argument can be one of the following: + + - `ocsp` + + - `caIssuers` + + - Any OID + +When *name* is OID, the value is the hexadecimal dumped Definite Encoding Rules +(DER) encoding of the `extnValue` for the extension excluding the OCTET STRING +type and length bytes. Other than standard hexadecimal numbers (0-9, a-f, A-F), +any extra characters are ignored in the HEX string. Therefore, both 01:02:03:04 +and 01020304 are accepted as identical values. When there is no value, the +extension has an empty value field. + +A special name `honored`, used only in `-gencert`, denotes how the extensions +included in the certificate request should be honored. The value for this name +is a comma-separated list of `all` (all requested extensions are honored), +*name*{`:`\[`critical`\|`non-critical`\]} (the named extension is honored, but +it uses a different `isCritical` attribute), and `-name` (used with `all`, +denotes an exception). Requested extensions aren't honored by default. + +If, besides the`-ext honored` option, another named or OID `-ext` option is +provided, this extension is added to those already honored. However, if this +name (or OID) also appears in the honored value, then its value and criticality +override that in the request. If an extension of the same type is provided +multiple times through either a name or an OID, only the last extension is +used. + +The `subjectKeyIdentifier` extension is always created. For non-self-signed +certificates, the `authorityKeyIdentifier` is created. + +**CAUTION:** + +Users should be aware that some combinations of extensions (and other +certificate fields) may not conform to the Internet standard. See [Certificate +Conformance Warning]. + +## Examples of Tasks in Creating a keystore + +The following examples describe the sequence actions in creating a keystore for +managing public/private key pairs and certificates from trusted entities. + +- [Generating the Key Pair] + +- [Requesting a Signed Certificate from a CA] + +- [Importing a Certificate for the CA] + +- [Importing the Certificate Reply from the CA] + +- [Exporting a Certificate That Authenticates the Public Key] + +- [Importing the Keystore] + +- [Generating Certificates for an SSL Server] + +## Generating the Key Pair + +Create a keystore and then generate the key pair. + +You can enter the command as a single line such as the following: + +> `keytool -genkeypair -dname "cn=myname, ou=mygroup, o=mycompany, + c=mycountry" -alias business -keyalg rsa -keypass` *password* `-keystore + /working/mykeystore -storepass password -validity 180` + +The command creates the keystore named `mykeystore` in the working directory +(provided it doesn't already exist), and assigns it the password specified by +`-keypass`. It generates a public/private key pair for the entity whose +distinguished name is `myname`, `mygroup`, `mycompany`, and a two-letter +country code of `mycountry`. It uses the RSA key generation algorithm +to create the keys; both are 3072 bits. + +The command uses the default SHA384withRSA signature algorithm to create a +self-signed certificate that includes the public key and the distinguished name +information. The certificate is valid for 180 days, and is associated with the +private key in a keystore entry referred to by `-alias business`. The private +key is assigned the password specified by `-keypass`. + +The command is significantly shorter when the option defaults are accepted. In +this case, only `-keyalg` is required, and the defaults are used for unspecified +options that have default values. You are prompted for any required values. You +could have the following: + +> `keytool -genkeypair -keyalg rsa` + +In this case, a keystore entry with the alias `mykey` is created, with a newly +generated key pair and a certificate that is valid for 90 days. This entry is +placed in your home directory in a keystore named `.keystore` . `.keystore` is +created if it doesn't already exist. You are prompted for the distinguished +name information, the keystore password, and the private key password. + +**Note:** + +The rest of the examples assume that you responded to the prompts with values +equal to those specified in the first `-genkeypair` command. For example, a +distinguished name of +`cn=`*myname*`, ou=`*mygroup*`, o=`*mycompany*`, c=`*mycountry*). + +## Requesting a Signed Certificate from a CA + +**Note:** + +Generating the key pair created a self-signed certificate; however, a +certificate is more likely to be trusted by others when it is signed by a CA. + +To get a CA signature, complete the following process: + +1. Generate a CSR: + + > `keytool -certreq -file myname.csr` + + This creates a CSR for the entity identified by the default alias `mykey` + and puts the request in the file named `myname.csr`. + +2. Submit `myname.csr` to a CA, such as DigiCert. + +The CA authenticates you, the requestor (usually offline), and returns a +certificate, signed by them, authenticating your public key. In some cases, the +CA returns a chain of certificates, each one authenticating the public key of +the signer of the previous certificate in the chain. + +## Importing a Certificate for the CA + +To import a certificate for the CA, complete the following process: + +1. Before you import the certificate reply from a CA, you need one or more + trusted certificates either in your keystore or in the `cacerts` keystore + file. See `-importcert` in **Commands**. + + - If the certificate reply is a certificate chain, then you need the top + certificate of the chain. The root CA certificate that authenticates + the public key of the CA. + + - If the certificate reply is a single certificate, then you need a + certificate for the issuing CA (the one that signed it). If that + certificate isn't self-signed, then you need a certificate for its + signer, and so on, up to a self-signed root CA certificate. + + The `cacerts` keystore ships with a set of root certificates issued by the + CAs of [the Oracle Java Root Certificate program]( + http://www.oracle.com/technetwork/java/javase/javasecarootcertsprogram-1876540.html). + If you request a signed certificate from a CA, and a certificate + authenticating that CA's public key hasn't been added to `cacerts`, then + you must import a certificate from that CA as a trusted certificate. + + A certificate from a CA is usually self-signed or signed by another CA. If + it is signed by another CA, you need a certificate that authenticates that + CA's public key. + + For example, you have obtained a *X*`.cer` file from a company that is a CA + and the file is supposed to be a self-signed certificate that authenticates + that CA's public key. Before you import it as a trusted certificate, you + should ensure that the certificate is valid by: + + 1. Viewing it with the `keytool -printcert` command or the + `keytool -importcert` command without using the `-noprompt` option. + Make sure that the displayed certificate fingerprints match the + expected fingerprints. + + 2. Calling the person who sent the certificate, and comparing the + fingerprints that you see with the ones that they show or that a secure + public key repository shows. + + Only when the fingerprints are equal is it assured that the certificate + wasn't replaced in transit with somebody else's certificate (such as an + attacker's certificate). If such an attack takes place, and you didn't + check the certificate before you imported it, then you would be trusting + anything that the attacker signed. + +2. Replace the self-signed certificate with a certificate chain, where each + certificate in the chain authenticates the public key of the signer of the + previous certificate in the chain, up to a root CA. + + If you trust that the certificate is valid, then you can add it to your + keystore by entering the following command: + + > `keytool -importcert -alias` *alias* `-file *X*`.cer` + + This command creates a trusted certificate entry in the keystore from the + data in the CA certificate file and assigns the values of the *alias* to + the entry. + +## Importing the Certificate Reply from the CA + +After you import a certificate that authenticates the public key of the CA that +you submitted your certificate signing request to (or there is already such a +certificate in the `cacerts` file), you can import the certificate reply and +replace your self-signed certificate with a certificate chain. + +The certificate chain is one of the following: + +- Returned by the CA when the CA reply is a chain. + +- Constructed when the CA reply is a single certificate. This certificate + chain is constructed by using the certificate reply and trusted + certificates available either in the keystore where you import the reply or + in the `cacerts` keystore file. + +For example, if you sent your certificate signing request to DigiCert, then you +can import their reply by entering the following command: + +**Note:** + +In this example, the returned certificate is named `DCmyname.cer`. + +> `keytool -importcert -trustcacerts -file DCmyname.cer` + +## Exporting a Certificate That Authenticates the Public Key + +**Note:** + +If you used the `jarsigner` command to sign a Java Archive (JAR) file, then +clients that use the file will want to authenticate your signature. + +One way that clients can authenticate you is by importing your public key +certificate into their keystore as a trusted entry. You can then export the +certificate and supply it to your clients. + +For example: + +1. Copy your certificate to a file named `myname.cer` by entering the + following command: + + **Note:** + + In this example, the entry has an alias of `mykey`. + + > `keytool -exportcert -alias mykey -file myname.cer` + +2. With the certificate and the signed JAR file, a client can use the + `jarsigner` command to authenticate your signature. + +## Importing the Keystore + +Use the `importkeystore` command to import an entire keystore into another +keystore. This imports all entries from the source keystore, including keys and +certificates, to the destination keystore with a single command. You can use +this command to import entries from a different type of keystore. During the +import, all new entries in the destination keystore will have the same alias +names and protection passwords (for secret keys and private keys). If the +`keytool` command can't recover the private keys or secret keys from the source +keystore, then it prompts you for a password. If it detects alias duplication, +then it asks you for a new alias, and you can specify a new alias or simply +allow the `keytool` command to overwrite the existing one. + +For example, import entries from a typical JKS type keystore `key.jks` into a +PKCS \#11 type hardware-based keystore, by entering the following command: + +> `keytool -importkeystore -srckeystore key.jks -destkeystore NONE + -srcstoretype JKS -deststoretype PKCS11 -srcstorepass` *password* + `-deststorepass` *password* + +The `importkeystore` command can also be used to import a single entry from a +source keystore to a destination keystore. In this case, besides the options +you used in the previous example, you need to specify the alias you want to +import. With the `-srcalias` option specified, you can also specify the +destination alias name, protection password for a secret or private key, and +the destination protection password you want as follows: + +> `keytool -importkeystore -srckeystore key.jks -destkeystore NONE + -srcstoretype JKS -deststoretype PKCS11 -srcstorepass` *password* + `-deststorepass` *password* `-srcalias myprivatekey -destalias + myoldprivatekey -srckeypass` *password* `-destkeypass` *password* + `-noprompt` + +## Generating Certificates for an SSL Server + +The following are `keytool` commands used to generate key pairs and +certificates for three entities: + +- Root CA (`root`) + +- Intermediate CA (`ca`) + +- SSL server (`server`) + +Ensure that you store all the certificates in the same keystore. + +``` +keytool -genkeypair -keystore root.jks -alias root -ext bc:c -keyalg rsa +keytool -genkeypair -keystore ca.jks -alias ca -ext bc:c -keyalg rsa +keytool -genkeypair -keystore server.jks -alias server -keyalg rsa + +keytool -keystore root.jks -alias root -exportcert -rfc > root.pem + +keytool -storepass password -keystore ca.jks -certreq -alias ca | + keytool -storepass password -keystore root.jks + -gencert -alias root -ext BC=0 -rfc > ca.pem +keytool -keystore ca.jks -importcert -alias ca -file ca.pem + +keytool -storepass password -keystore server.jks -certreq -alias server | + keytool -storepass password -keystore ca.jks -gencert -alias ca + -ext ku:c=dig,kE -rfc > server.pem +cat root.pem ca.pem server.pem | + keytool -keystore server.jks -importcert -alias server + +``` + +## Terms + +Keystore +: A keystore is a storage facility for cryptographic keys and certificates. + +Keystore entries +: Keystores can have different types of entries. The two most applicable + entry types for the `keytool` command include the following: + + Key entries: Each entry holds very sensitive cryptographic key information, + which is stored in a protected format to prevent unauthorized access. + Typically, a key stored in this type of entry is a secret key, or a private + key accompanied by the certificate chain for the corresponding public key. + See **Certificate Chains**. The `keytool` command can handle both types of + entries, while the `jarsigner` tool only handles the latter type of entry, + that is private keys and their associated certificate chains. + + Trusted certificate entries: Each entry contains a single public key + certificate that belongs to another party. The entry is called a trusted + certificate because the keystore owner trusts that the public key in the + certificate belongs to the identity identified by the subject (owner) of + the certificate. The issuer of the certificate vouches for this, by signing + the certificate. + +Keystore aliases +: All keystore entries (key and trusted certificate entries) are accessed by + way of unique aliases. + + An alias is specified when you add an entity to the keystore with the + `-genseckey` command to generate a secret key, the `-genkeypair` command to + generate a key pair (public and private key), or the `-importcert` command + to add a certificate or certificate chain to the list of trusted + certificates. Subsequent `keytool` commands must use this same alias to + refer to the entity. + + For example, you can use the alias `duke` to generate a new public/private + key pair and wrap the public key into a self-signed certificate with the + following command. See **Certificate Chains**. + + > `keytool -genkeypair -alias duke -keyalg rsa -keypass` *passwd* + + This example specifies an initial *passwd* required by subsequent commands + to access the private key associated with the alias `duke`. If you later + want to change Duke's private key password, use a command such as the + following: + + > `keytool -keypasswd -alias duke -keypass` *passwd* `-new` *newpasswd* + + This changes the initial *passwd* to *newpasswd*. A password shouldn't be + specified on a command line or in a script unless it is for testing + purposes, or you are on a secure system. If you don't specify a required + password option on a command line, then you are prompted for it. + +Keystore implementation +: The `KeyStore` class provided in the `java.security` package supplies + well-defined interfaces to access and modify the information in a keystore. + It is possible for there to be multiple different concrete implementations, + where each implementation is that for a particular type of keystore. + + Currently, two command-line tools (`keytool` and `jarsigner`) make use of + keystore implementations. Because the `KeyStore` class is `public`, users + can write additional security applications that use it. + + In JDK 9 and later, the default keystore implementation is `PKCS12`. This + is a cross platform keystore based on the RSA PKCS12 Personal Information + Exchange Syntax Standard. This standard is primarily meant for storing or + transporting a user's private keys, certificates, and miscellaneous + secrets. There is another built-in implementation, provided by Oracle. It + implements the keystore as a file with a proprietary keystore type (format) + named `JKS`. It protects each private key with its individual password, and + also protects the integrity of the entire keystore with a (possibly + different) password. + + Keystore implementations are provider-based. More specifically, the + application interfaces supplied by `KeyStore` are implemented in terms of a + Service Provider Interface (SPI). That is, there is a corresponding + abstract `KeystoreSpi` class, also in the `java.security package`, which + defines the Service Provider Interface methods that providers must + implement. The term *provider* refers to a package or a set of packages + that supply a concrete implementation of a subset of services that can be + accessed by the Java Security API. To provide a keystore implementation, + clients must implement a provider and supply a `KeystoreSpi` subclass + implementation, as described in Steps to Implement and Integrate a + Provider. + + Applications can choose different types of keystore implementations from + different providers, using the `getInstance` factory method supplied in the + `KeyStore` class. A keystore type defines the storage and data format of + the keystore information, and the algorithms used to protect private/secret + keys in the keystore and the integrity of the keystore. Keystore + implementations of different types aren't compatible. + + The `keytool` command works on any file-based keystore implementation. It + treats the keystore location that is passed to it at the command line as a + file name and converts it to a `FileInputStream`, from which it loads the + keystore information.)The `jarsigner` commands can read a keystore from any + location that can be specified with a URL. + + For `keytool` and `jarsigner`, you can specify a keystore type at the + command line, with the `-storetype` option. + + If you don't explicitly specify a keystore type, then the tools choose a + keystore implementation based on the value of the `keystore.type` property + specified in the security properties file. The security properties file is + called `java.security`, and resides in the security properties directory: + + - **Linux and macOS:** `java.home/lib/security` + + - **Windows:** `java.home\lib\security` + + Each tool gets the `keystore.type` value and then examines all the + currently installed providers until it finds one that implements a + keystores of that type. It then uses the keystore implementation from that + provider.The `KeyStore` class defines a static method named + `getDefaultType` that lets applications retrieve the value of the + `keystore.type` property. The following line of code creates an instance of + the default keystore type as specified in the `keystore.type` property: + + > `KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());` + + The default keystore type is `pkcs12`, which is a cross-platform keystore + based on the RSA PKCS12 Personal Information Exchange Syntax Standard. This + is specified by the following line in the security properties file: + + > `keystore.type=pkcs12` + + To have the tools utilize a keystore implementation other than the default, + you can change that line to specify a different keystore type. For example, + if you want to use the Oracle's `jks` keystore implementation, then change + the line to the following: + + > `keystore.type=jks` + + **Note:** + + Case doesn't matter in keystore type designations. For example, `JKS` would + be considered the same as `jks`. + +Certificate +: A certificate (or public-key certificate) is a digitally signed statement + from one entity (the issuer), saying that the public key and some other + information of another entity (the subject) has some specific value. The + following terms are related to certificates: + + - Public Keys: These are numbers associated with a particular entity, and + are intended to be known to everyone who needs to have trusted + interactions with that entity. Public keys are used to verify + signatures. + + - Digitally Signed: If some data is digitally signed, then it is stored + with the identity of an entity and a signature that proves that entity + knows about the data. The data is rendered unforgeable by signing with + the entity's private key. + + - Identity: A known way of addressing an entity. In some systems, the + identity is the public key, and in others it can be anything from an + Oracle Solaris UID to an email address to an X.509 distinguished name. + + - Signature: A signature is computed over some data using the private key + of an entity. The signer, which in the case of a certificate is also + known as the issuer. + + - Private Keys: These are numbers, each of which is supposed to be known + only to the particular entity whose private key it is (that is, it is + supposed to be kept secret). Private and public keys exist in pairs in + all public key cryptography systems (also referred to as public key + crypto systems). In a typical public key crypto system, such as DSA, a + private key corresponds to exactly one public key. Private keys are + used to compute signatures. + + - Entity: An entity is a person, organization, program, computer, + business, bank, or something else you are trusting to some degree. + + Public key cryptography requires access to users' public keys. In a + large-scale networked environment, it is impossible to guarantee that prior + relationships between communicating entities were established or that a + trusted repository exists with all used public keys. Certificates were + invented as a solution to this public key distribution problem. Now a + Certification Authority (CA) can act as a trusted third party. CAs are + entities such as businesses that are trusted to sign (issue) certificates + for other entities. It is assumed that CAs only create valid and reliable + certificates because they are bound by legal agreements. There are many + public Certification Authorities, such as DigiCert, Comodo, Entrust, and so + on. + + You can also run your own Certification Authority using products such as + Microsoft Certificate Server or the Entrust CA product for your + organization. With the `keytool` command, it is possible to display, + import, and export certificates. It is also possible to generate + self-signed certificates. + + The `keytool` command currently handles X.509 certificates. + +X.509 Certificates +: The X.509 standard defines what information can go into a certificate and + describes how to write it down (the data format). All the data in a + certificate is encoded with two related standards called ASN.1/DER. + Abstract Syntax Notation 1 describes data. The Definite Encoding Rules + describe a single way to store and transfer that data. + + All X.509 certificates have the following data, in addition to the + signature: + + - Version: This identifies which version of the X.509 standard applies to + this certificate, which affects what information can be specified in + it. Thus far, three versions are defined. The `keytool` command can + import and export v1, v2, and v3 certificates. It generates v3 + certificates. + + - X.509 Version 1 has been available since 1988, is widely deployed, + and is the most generic. + + - X.509 Version 2 introduced the concept of subject and issuer unique + identifiers to handle the possibility of reuse of subject or issuer + names over time. Most certificate profile documents strongly + recommend that names not be reused and that certificates shouldn't + make use of unique identifiers. Version 2 certificates aren't + widely used. + + - X.509 Version 3 is the most recent (1996) and supports the notion + of extensions where anyone can define an extension and include it + in the certificate. Some common extensions are: KeyUsage (limits + the use of the keys to particular purposes such as `signing-only`) + and AlternativeNames (allows other identities to also be associated + with this public key, for example. DNS names, email addresses, IP + addresses). Extensions can be marked critical to indicate that the + extension should be checked and enforced or used. For example, if a + certificate has the KeyUsage extension marked critical and set to + `keyCertSign`, then when this certificate is presented during SSL + communication, it should be rejected because the certificate + extension indicates that the associated private key should only be + used for signing certificates and not for SSL use. + + - Serial number: The entity that created the certificate is responsible + for assigning it a serial number to distinguish it from other + certificates it issues. This information is used in numerous ways. For + example, when a certificate is revoked its serial number is placed in a + Certificate Revocation List (CRL). + + - Signature algorithm identifier: This identifies the algorithm used by + the CA to sign the certificate. + + - Issuer name: The X.500 Distinguished Name of the entity that signed the + certificate. This is typically a CA. Using this certificate implies + trusting the entity that signed this certificate. In some cases, such + as root or top-level CA certificates, the issuer signs its own + certificate. + + - Validity period: Each certificate is valid only for a limited amount of + time. This period is described by a start date and time and an end date + and time, and can be as short as a few seconds or almost as long as a + century. The validity period chosen depends on a number of factors, + such as the strength of the private key used to sign the certificate, + or the amount one is willing to pay for a certificate. This is the + expected period that entities can rely on the public value, when the + associated private key has not been compromised. + + - Subject name: The name of the entity whose public key the certificate + identifies. This name uses the X.500 standard, so it is intended to be + unique across the Internet. This is the X.500 Distinguished Name (DN) + of the entity. For example, + + > `CN=Java Duke, OU=Java Software Division, O=Oracle Corporation, + C=US` + + These refer to the subject's common name (CN), organizational unit + (OU), organization (O), and country (C). + + - Subject public key information: This is the public key of the entity + being named with an algorithm identifier that specifies which public + key crypto system this key belongs to and any associated key + parameters. + +Certificate Chains +: The `keytool` command can create and manage keystore key entries that each + contain a private key and an associated certificate chain. The first + certificate in the chain contains the public key that corresponds to the + private key. + + When keys are first generated, the chain usually starts off containing a single + element, a self-signed certificate. See -genkeypair in **Commands**. A + self-signed certificate is one for which the issuer (signer) is the same as + the subject. The subject is the entity whose public key is being + authenticated by the certificate. When the `-genkeypair` command is called + to generate a new public/private key pair, it also wraps the public key + into a self-signed certificate (unless the `-signer` option is specified). + + Later, after a Certificate Signing Request (CSR) was generated with the + `-certreq` command and sent to a Certification Authority (CA), the response + from the CA is imported with `-importcert`, and the self-signed certificate + is replaced by a chain of certificates. At the bottom of the chain is the + certificate (reply) issued by the CA authenticating the subject's public + key. The next certificate in the chain is one that authenticates the CA's + public key. + + In many cases, this is a self-signed certificate, which is a certificate + from the CA authenticating its own public key, and the last certificate in + the chain. In other cases, the CA might return a chain of certificates. In + this case, the bottom certificate in the chain is the same (a certificate + signed by the CA, authenticating the public key of the key entry), but the + second certificate in the chain is a certificate signed by a different CA + that authenticates the public key of the CA you sent the CSR to. The next + certificate in the chain is a certificate that authenticates the second + CA's key, and so on, until a self-signed root certificate is reached. Each + certificate in the chain (after the first) authenticates the public key of + the signer of the previous certificate in the chain. + + Many CAs only return the issued certificate, with no supporting chain, + especially when there is a flat hierarchy (no intermediates CAs). In this + case, the certificate chain must be established from trusted certificate + information already stored in the keystore. + + A different reply format (defined by the PKCS \#7 standard) includes the + supporting certificate chain in addition to the issued certificate. Both + reply formats can be handled by the `keytool` command. + + The top-level (root) CA certificate is self-signed. However, the trust into + the root's public key doesn't come from the root certificate itself, but + from other sources such as a newspaper. This is because anybody could + generate a self-signed certificate with the distinguished name of, for + example, the DigiCert root CA. The root CA public key is widely known. The + only reason it is stored in a certificate is because this is the format + understood by most tools, so the certificate in this case is only used as a + vehicle to transport the root CA's public key. Before you add the root CA + certificate to your keystore, you should view it with the `-printcert` + option and compare the displayed fingerprint with the well-known + fingerprint obtained from a newspaper, the root CA's Web page, and so on. + +cacerts Certificates File +: A certificates file named `cacerts` resides in the security properties + directory: + + - **Linux and macOS:** *JAVA\_HOME*`/lib/security` + + - **Windows:** *JAVA\_HOME*`\lib\security` + + The `cacerts` file represents a system-wide keystore with CA certificates. + System administrators can configure and manage that file with the `keytool` + command by specifying `jks` as the keystore type. The `cacerts` keystore + file ships with a default set of root CA certificates. For Linux, macOS, and + Windows, you can list the default certificates with the following command: + + > `keytool -list -cacerts` + + The initial password of the `cacerts` keystore file is `changeit`. System + administrators should change that password and the default access + permission of that file upon installing the SDK. + + **Note:** + + It is important to verify your `cacerts` file. Because you trust the CAs in + the `cacerts` file as entities for signing and issuing certificates to + other entities, you must manage the `cacerts` file carefully. The `cacerts` + file should contain only certificates of the CAs you trust. It is your + responsibility to verify the trusted root CA certificates bundled in the + `cacerts` file and make your own trust decisions. + + To remove an untrusted CA certificate from the `cacerts` file, use the + `-delete` option of the `keytool` command. You can find the `cacerts` file + in the JDK's `$JAVA_HOME/lib/security` directory. Contact your system + administrator if you don't have permission to edit this file. + +Internet RFC 1421 Certificate Encoding Standard +: Certificates are often stored using the printable encoding format defined + by the Internet RFC 1421 standard, instead of their binary encoding. This + certificate format, also known as Base64 encoding, makes it easy to export + certificates to other applications by email or through some other + mechanism. + + Certificates read by the `-importcert` and `-printcert` commands can be in + either this format or binary encoded. The `-exportcert` command by default + outputs a certificate in binary encoding, but will instead output a + certificate in the printable encoding format, when the `-rfc` option is + specified. + + The `-list` command by default prints the SHA-256 fingerprint of a + certificate. If the `-v` option is specified, then the certificate is + printed in human-readable format. If the `-rfc` option is specified, then + the certificate is output in the printable encoding format. + + In its printable encoding format, the encoded certificate is bounded at the + beginning and end by the following text: + + ``` + -----BEGIN CERTIFICATE----- + + encoded certificate goes here. + + -----END CERTIFICATE----- + ``` + +X.500 Distinguished Names +: X.500 Distinguished Names are used to identify entities, such as those that + are named by the `subject` and `issuer` (signer) fields of X.509 + certificates. The `keytool` command supports the following subparts: + + - commonName: The common name of a person such as Susan Jones. + + - organizationUnit: The small organization (such as department or + division) name. For example, Purchasing. + + - localityName: The locality (city) name, for example, Palo Alto. + + - stateName: State or province name, for example, California. + + - country: Two-letter country code, for example, CH. + + When you supply a distinguished name string as the value of a `-dname` + option, such as for the `-genkeypair` command, the string must be in the + following format: + + > `CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode` + + All the following items represent actual values and the previous keywords + are abbreviations for the following: + + ``` + CN=commonName + OU=organizationUnit + O=organizationName + L=localityName + S=stateName + C=country + ``` + + A sample distinguished name string is: + + > `CN=Mark Smith, OU=Java, O=Oracle, L=Cupertino, S=California, C=US` + + A sample command using such a string is: + + > `keytool -genkeypair -dname "CN=Mark Smith, OU=Java, O=Oracle, + L=Cupertino, S=California, C=US" -alias mark -keyalg rsa` + + Case doesn't matter for the keyword abbreviations. For example, CN, cn, and + Cn are all treated the same. + + Order matters; each subcomponent must appear in the designated order. + However, it isn't necessary to have all the subcomponents. You can use a + subset, for example: + + > `CN=Smith, OU=Java, O=Oracle, C=US` + + If a distinguished name string value contains a comma, then the comma must + be escaped by a backslash (\\) character when you specify the string on a + command line, as in: + + > `cn=Jack, ou=Java\, Product Development, o=Oracle, c=US` + + It is never necessary to specify a distinguished name string on a command + line. When the distinguished name is needed for a command, but not supplied + on the command line, the user is prompted for each of the subcomponents. In + this case, a comma doesn't need to be escaped by a backslash (\\). + +## Warnings + +## Importing Trusted Certificates Warning + +**Important**: Be sure to check a certificate very carefully before importing +it as a trusted certificate. + +**Windows Example:** + +View the certificate first with the `-printcert` command or the `-importcert` +command without the `-noprompt` option. Ensure that the displayed certificate +fingerprints match the expected ones. For example, suppose someone sends or +emails you a certificate that you put it in a file named `\tmp\cert`. Before +you consider adding the certificate to your list of trusted certificates, you +can execute a `-printcert` command to view its fingerprints, as follows: + +``` + keytool -printcert -file \tmp\cert + Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll + Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll + Serial Number: 59092b34 + Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016 + Certificate Fingerprints: + + SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE + SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90: + 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4 +``` + +**Linux Example:** + +View the certificate first with the `-printcert` command or the `-importcert` +command without the `-noprompt` option. Ensure that the displayed certificate +fingerprints match the expected ones. For example, suppose someone sends or +emails you a certificate that you put it in a file named `/tmp/cert`. Before +you consider adding the certificate to your list of trusted certificates, you +can execute a `-printcert` command to view its fingerprints, as follows: + +``` + keytool -printcert -file /tmp/cert + Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll + Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll + Serial Number: 59092b34 + Valid from: Thu Jun 24 18:01:13 PDT 2016 until: Wed Jun 23 17:01:13 PST 2016 + Certificate Fingerprints: + + SHA-1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE + SHA-256: 90:7B:70:0A:EA:DC:16:79:92:99:41:FF:8A:FE:EB:90: + 17:75:E0:90:B2:24:4D:3A:2A:16:A6:E4:11:0F:67:A4 +``` + +Then call or otherwise contact the person who sent the certificate and compare +the fingerprints that you see with the ones that they show. Only when the +fingerprints are equal is it guaranteed that the certificate wasn't replaced in +transit with somebody else's certificate such as an attacker's certificate. If +such an attack took place, and you didn't check the certificate before you +imported it, then you would be trusting anything the attacker signed, for +example, a JAR file with malicious class files inside. + +**Note:** + +It isn't required that you execute a `-printcert` command before importing a +certificate. This is because before you add a certificate to the list of +trusted certificates in the keystore, the `-importcert` command prints out the +certificate information and prompts you to verify it. You can then stop the +import operation. However, you can do this only when you call the `-importcert` +command without the `-noprompt` option. If the `-noprompt` option is specified, +then there is no interaction with the user. + +## Passwords Warning + +Most commands that operate on a keystore require the store password. Some +commands require a private/secret key password. Passwords can be specified on +the command line in the `-storepass` and `-keypass` options. However, a +password shouldn't be specified on a command line or in a script unless it is +for testing, or you are on a secure system. When you don't specify a required +password option on a command line, you are prompted for it. + +## Certificate Conformance Warning + +[Internet X.509 Public Key Infrastructure Certificate and Certificate +Revocation List (CRL) Profile](https://tools.ietf.org/rfc/rfc5280.txt) defined +a profile on conforming X.509 certificates, which includes what values and +value combinations are valid for certificate fields and extensions. + +The `keytool` command doesn't enforce all of these rules so it can generate +certificates that don't conform to the standard, such as self-signed +certificates that would be used for internal testing purposes. Certificates +that don't conform to the standard might be rejected by the JDK or other +applications. Users should ensure that they provide the correct options for +`-dname`, `-ext`, and so on. + +## Import a New Trusted Certificate + +Before you add the certificate to the keystore, the `keytool` command verifies +it by attempting to construct a chain of trust from that certificate to a +self-signed certificate (belonging to a root CA), using trusted certificates +that are already available in the keystore. + +If the `-trustcacerts` option was specified, then additional certificates are +considered for the chain of trust, namely the certificates in a file named +`cacerts`. + +If the `keytool` command fails to establish a trust path from the certificate +to be imported up to a self-signed certificate (either from the keystore or the +`cacerts` file), then the certificate information is printed, and the user is +prompted to verify it by comparing the displayed certificate fingerprints with +the fingerprints obtained from some other (trusted) source of information, +which might be the certificate owner. Be very careful to ensure the certificate +is valid before importing it as a trusted certificate. The user then has the +option of stopping the import operation. If the `-noprompt` option is +specified, then there is no interaction with the user. + +## Import a Certificate Reply + +When you import a certificate reply, the certificate reply is validated with +trusted certificates from the keystore, and optionally, the certificates +configured in the `cacerts` keystore file when the `-trustcacerts` option is +specified. + +The methods of determining whether the certificate reply is trusted are as +follows: + +- If the reply is a single X.509 certificate, then the `keytool` command + attempts to establish a trust chain, starting at the certificate reply and + ending at a self-signed certificate (belonging to a root CA). The + certificate reply and the hierarchy of certificates is used to authenticate + the certificate reply from the new certificate chain of aliases. If a trust + chain can't be established, then the certificate reply isn't imported. In + this case, the `keytool` command doesn't print the certificate and prompt + the user to verify it, because it is very difficult for a user to determine + the authenticity of the certificate reply. + +- If the reply is a PKCS \#7 formatted certificate chain or a sequence of + X.509 certificates, then the chain is ordered with the user certificate + first followed by zero or more CA certificates. If the chain ends with a + self-signed root CA certificate and the`-trustcacerts` option was + specified, the `keytool` command attempts to match it with any of the + trusted certificates in the keystore or the `cacerts` keystore file. If the + chain doesn't end with a self-signed root CA certificate and the + `-trustcacerts` option was specified, the `keytool` command tries to find + one from the trusted certificates in the keystore or the `cacerts` keystore + file and add it to the end of the chain. If the certificate isn't found and + the `-noprompt` option isn't specified, the information of the last + certificate in the chain is printed, and the user is prompted to verify it. + +If the public key in the certificate reply matches the user's public key +already stored with `alias`, then the old certificate chain is replaced with +the new certificate chain in the reply. The old chain can only be replaced with +a valid `keypass`, and so the password used to protect the private key of the +entry is supplied. If no password is provided, and the private key password is +different from the keystore password, the user is prompted for it. + +This command was named `-import` in earlier releases. This old name is still +supported in this release. The new name, `-importcert`, is preferred. diff --git a/src/java.rmi/share/man/rmiregistry.1 b/src/java.rmi/share/man/rmiregistry.1 deleted file mode 100644 index c168e1482a6..00000000000 --- a/src/java.rmi/share/man/rmiregistry.1 +++ /dev/null @@ -1,100 +0,0 @@ -.\" Copyright (c) 1997, 2018, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "RMIREGISTRY" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -rmiregistry - create and start a remote object registry on the specified -port on the current host -.SH SYNOPSIS -.PP -\f[V]rmiregistry\f[R] [\f[I]options\f[R]] [\f[I]port\f[R]] -.TP -\f[I]options\f[R] -This represents the option for the \f[V]rmiregistry\f[R] command. -See \f[B]Options\f[R] -.TP -\f[I]port\f[R] -The number of a port on the current host at which to start the remote -object registry. -.SH DESCRIPTION -.PP -The \f[V]rmiregistry\f[R] command creates and starts a remote object -registry on the specified port on the current host. -If the port is omitted, then the registry is started on port 1099. -The \f[V]rmiregistry\f[R] command produces no output and is typically -run in the background, for example: -.RS -.PP -\f[V]rmiregistry &\f[R] -.RE -.PP -A remote object registry is a bootstrap naming service that\[aq]s used -by RMI servers on the same host to bind remote objects to names. -Clients on local and remote hosts can then look up remote objects and -make remote method invocations. -.PP -The registry is typically used to locate the first remote object on -which an application needs to call methods. -That object then provides application-specific support for finding other -objects. -.PP -The methods of the \f[V]java.rmi.registry.LocateRegistry\f[R] class are -used to get a registry operating on the local host or local host and -port. -.PP -The URL-based methods of the \f[V]java.rmi.Naming\f[R] class operate on -a registry and can be used to: -.IP \[bu] 2 -Bind the specified name to a remote object -.IP \[bu] 2 -Return an array of the names bound in the registry -.IP \[bu] 2 -Return a reference, a stub, for the remote object associated with the -specified name -.IP \[bu] 2 -Rebind the specified name to a new remote object -.IP \[bu] 2 -Destroy the binding for the specified name that\[aq]s associated with a -remote object -.SH OPTIONS -.TP -\f[V]-J\f[R]\f[I]option\f[R] -Used with any Java option to pass the \f[I]option\f[R] following the -\f[V]-J\f[R] (no spaces between the \f[V]-J\f[R] and the option) to the -Java interpreter. diff --git a/src/java.rmi/share/man/rmiregistry.md b/src/java.rmi/share/man/rmiregistry.md new file mode 100644 index 00000000000..48c426cfbdc --- /dev/null +++ b/src/java.rmi/share/man/rmiregistry.md @@ -0,0 +1,86 @@ +--- +# Copyright (c) 1997, 2018, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'RMIREGISTRY(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +rmiregistry - create and start a remote object registry on the specified port +on the current host + +## Synopsis + +`rmiregistry` \[*options*\] \[*port*\] + +*options* +: This represents the option for the `rmiregistry` command. See + [Options] + +*port* +: The number of a port on the current host at which to start the remote + object registry. + +## Description + +The `rmiregistry` command creates and starts a remote object registry on the +specified port on the current host. If the port is omitted, then the registry +is started on port 1099. The `rmiregistry` command produces no output and is +typically run in the background, for example: + +> `rmiregistry &` + +A remote object registry is a bootstrap naming service that's used by RMI +servers on the same host to bind remote objects to names. Clients on local and +remote hosts can then look up remote objects and make remote method +invocations. + +The registry is typically used to locate the first remote object on which an +application needs to call methods. That object then provides +application-specific support for finding other objects. + +The methods of the `java.rmi.registry.LocateRegistry` class are used to get a +registry operating on the local host or local host and port. + +The URL-based methods of the `java.rmi.Naming` class operate on a registry and +can be used to: + +- Bind the specified name to a remote object + +- Return an array of the names bound in the registry + +- Return a reference, a stub, for the remote object associated with the + specified name + +- Rebind the specified name to a new remote object + +- Destroy the binding for the specified name that's associated with a remote + object + +## Options + +`-J`*option* +: Used with any Java option to pass the *option* following the `-J` (no + spaces between the `-J` and the option) to the Java interpreter. diff --git a/src/java.scripting/share/man/jrunscript.1 b/src/java.scripting/share/man/jrunscript.1 deleted file mode 100644 index 491c3cb3be3..00000000000 --- a/src/java.scripting/share/man/jrunscript.1 +++ /dev/null @@ -1,166 +0,0 @@ -.\" Copyright (c) 2006, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JRUNSCRIPT" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -jrunscript - run a command-line script shell that supports interactive -and batch modes -.SH SYNOPSIS -.PP -\f[B]Note:\f[R] -.PP -This tool is \f[B]experimental\f[R] and unsupported. -It is deprecated and will be removed in a future release. -.PP -\f[V]jrunscript\f[R] [\f[I]options\f[R]] [\f[I]arguments\f[R]] -.TP -\f[I]options\f[R] -This represents the \f[V]jrunscript\f[R] command-line options that can -be used. -See \f[B]Options for the jrunscript Command\f[R]. -.TP -\f[I]arguments\f[R] -Arguments, when used, follow immediately after options or the command -name. -See \f[B]Arguments\f[R]. -.SH DESCRIPTION -.PP -The \f[V]jrunscript\f[R] command is a language-independent command-line -script shell. -The \f[V]jrunscript\f[R] command supports both an interactive -(read-eval-print) mode and a batch (\f[V]-f\f[R] option) mode of script -execution. -By default, JavaScript is the language used, but the \f[V]-l\f[R] option -can be used to specify a different language. -By using Java to scripting language communication, the -\f[V]jrunscript\f[R] command supports an exploratory programming style. -.PP -If JavaScript is used, then before it evaluates a user defined script, -the \f[V]jrunscript\f[R] command initializes certain built-in functions -and objects, which are documented in the API Specification for -\f[V]jrunscript\f[R] JavaScript built-in functions. -.SH OPTIONS FOR THE JRUNSCRIPT COMMAND -.TP -\f[V]-cp\f[R] \f[I]path\f[R] or \f[V]-classpath\f[R] \f[I]path\f[R] -Indicates where any class files are that the script needs to access. -.TP -\f[V]-D\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R] -Sets a Java system property. -.TP -\f[V]-J\f[R]\f[I]flag\f[R] -Passes \f[I]flag\f[R] directly to the Java Virtual Machine where the -\f[V]jrunscript\f[R] command is running. -.TP -\f[V]-l\f[R] \f[I]language\f[R] -Uses the specified scripting language. -By default, JavaScript is used. -To use other scripting languages, you must specify the corresponding -script engine\[aq]s JAR file with the \f[V]-cp\f[R] or -\f[V]-classpath\f[R] option. -.TP -\f[V]-e\f[R] \f[I]script\f[R] -Evaluates the specified script. -This option can be used to run one-line scripts that are specified -completely on the command line. -.TP -\f[V]-encoding\f[R] \f[I]encoding\f[R] -Specifies the character encoding used to read script files. -.TP -\f[V]-f\f[R] \f[I]script-file\f[R] -Evaluates the specified script file (batch mode). -.TP -\f[V]-f -\f[R] -Enters interactive mode to read and evaluate a script from standard -input. -.TP -\f[V]-help\f[R] or \f[V]-?\f[R] -Displays a help message and exits. -.TP -\f[V]-q\f[R] -Lists all script engines available and exits. -.SH ARGUMENTS -.PP -If arguments are present and if no \f[V]-e\f[R] or \f[V]-f\f[R] option -is used, then the first argument is the script file and the rest of the -arguments, if any, are passed as script arguments. -If arguments and the \f[V]-e\f[R] or the \f[V]-f\f[R] option are used, -then all arguments are passed as script arguments. -If arguments \f[V]-e\f[R] and \f[V]-f\f[R] are missing, then the -interactive mode is used. -.SH EXAMPLE OF EXECUTING INLINE SCRIPTS -.RS -.PP -\f[V]jrunscript -e \[dq]print(\[aq]hello world\[aq])\[dq]\f[R] -.RE -.RS -.PP -\f[V]jrunscript -e \[dq]cat(\[aq]http://www.example.com\[aq])\[dq]\f[R] -.RE -.SH EXAMPLE OF USING SPECIFIED LANGUAGE AND EVALUATE THE SCRIPT FILE -.RS -.PP -\f[V]jrunscript -l js -f test.js\f[R] -.RE -.SH EXAMPLE OF INTERACTIVE MODE -.IP -.nf -\f[CB] -jrunscript -js> print(\[aq]Hello World\[rs]n\[aq]); -Hello World -js> 34 + 55 -89.0 -js> t = new java.lang.Thread(function() { print(\[aq]Hello World\[rs]n\[aq]); }) -Thread[Thread-0,5,main] -js> t.start() -js> Hello World - -js> -\f[R] -.fi -.SH RUN SCRIPT FILE WITH SCRIPT ARGUMENTS -.PP -In this example, the \f[V]test.js\f[R] file is the script file. -The \f[V]arg1\f[R], \f[V]arg2\f[R], and \f[V]arg3\f[R] arguments are -passed to the script. -The script can access these arguments with an arguments array. -.RS -.PP -\f[V]jrunscript test.js arg1 arg2 arg3\f[R] -.RE diff --git a/src/java.scripting/share/man/jrunscript.md b/src/java.scripting/share/man/jrunscript.md new file mode 100644 index 00000000000..85ace0c32ee --- /dev/null +++ b/src/java.scripting/share/man/jrunscript.md @@ -0,0 +1,141 @@ +--- +# Copyright (c) 2006, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JRUNSCRIPT(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jrunscript - run a command-line script shell that supports interactive and +batch modes + +## Synopsis + +**Note:** + +This tool is **experimental** and unsupported. It is deprecated and will be +removed in a future release. + +`jrunscript` \[*options*\] \[*arguments*\] + +*options* +: This represents the `jrunscript` command-line options that can be used. See + [Options for the jrunscript Command]. + +*arguments* +: Arguments, when used, follow immediately after options or the command name. + See [Arguments]. + +## Description + +The `jrunscript` command is a language-independent command-line script shell. +The `jrunscript` command supports both an interactive (read-eval-print) mode +and a batch (`-f` option) mode of script execution. By default, JavaScript is +the language used, but the `-l` option can be used to specify a different +language. By using Java to scripting language communication, the `jrunscript` +command supports an exploratory programming style. + +If JavaScript is used, then before it evaluates a user defined script, the +`jrunscript` command initializes certain built-in functions and objects, which +are documented in the API Specification for `jrunscript` JavaScript built-in +functions. + +## Options for the jrunscript Command + +`-cp` *path* or `-classpath` *path* +: Indicates where any class files are that the script needs to access. + +`-D`*name*`=`*value* +: Sets a Java system property. + +`-J`*flag* +: Passes *flag* directly to the Java Virtual Machine where the `jrunscript` + command is running. + +`-l` *language* +: Uses the specified scripting language. By default, JavaScript is used. To + use other scripting languages, you must specify the corresponding script + engine's JAR file with the `-cp` or `-classpath` option. + +`-e` *script* +: Evaluates the specified script. This option can be used to run one-line + scripts that are specified completely on the command line. + +`-encoding` *encoding* +: Specifies the character encoding used to read script files. + +`-f` *script-file* +: Evaluates the specified script file (batch mode). + +`-f -` +: Enters interactive mode to read and evaluate a script from standard input. + +`-help` or `-?` +: Displays a help message and exits. + +`-q` +: Lists all script engines available and exits. + +## Arguments + +If arguments are present and if no `-e` or `-f` option is used, then the first +argument is the script file and the rest of the arguments, if any, are passed +as script arguments. If arguments and the `-e` or the `-f` option are used, +then all arguments are passed as script arguments. If arguments `-e` and `-f` +are missing, then the interactive mode is used. + +## Example of Executing Inline Scripts + +> `jrunscript -e "print('hello world')"` + +> `jrunscript -e "cat('http://www.example.com')"` + +## Example of Using Specified Language and Evaluate the Script File + +> `jrunscript -l js -f test.js` + +## Example of Interactive Mode + +``` +jrunscript +js> print('Hello World\n'); +Hello World +js> 34 + 55 +89.0 +js> t = new java.lang.Thread(function() { print('Hello World\n'); }) +Thread[Thread-0,5,main] +js> t.start() +js> Hello World + +js> +``` + +## Run Script File with Script Arguments + +In this example, the `test.js` file is the script file. The `arg1`, `arg2`, and +`arg3` arguments are passed to the script. The script can access these +arguments with an arguments array. + +> `jrunscript test.js arg1 arg2 arg3` diff --git a/src/java.security.jgss/windows/man/kinit.md b/src/java.security.jgss/windows/man/kinit.md new file mode 100644 index 00000000000..03605667ae9 --- /dev/null +++ b/src/java.security.jgss/windows/man/kinit.md @@ -0,0 +1,154 @@ +--- +# Copyright (c) 2005, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'KINIT(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +kinit - obtain and cache Kerberos ticket-granting tickets + +## Synopsis + +Initial ticket request: + +`kinit` \[`-A`\] \[`-f`\] \[`-p`\] \[`-c` *cache\_name*\] \[`-l` *lifetime*\] +\[`-r` *renewable\_time*\] \[\[`-k` \[`-t` *keytab\_file\_name*\]\] +\[*principal*\] \[*password*\] + +Renew a ticket: + +`kinit` `-R` \[`-c` *cache\_name*\] \[*principal*\] + +## Description + +This tool is similar in functionality to the `kinit` tool that is commonly +found in other Kerberos implementations, such as SEAM and MIT Reference +implementations. The user must be registered as a principal with the Key +Distribution Center (KDC) prior to running `kinit`. + +By default, on Windows, a cache file named *USER\_HOME*`\krb5cc_`*USER\_NAME* +is generated. + +The identifier *USER\_HOME* is obtained from the `java.lang.System` property +`user.home`. *USER\_NAME* is obtained from the `java.lang.System` property +`user.name`. If *USER\_HOME* is null, the cache file is stored in the current +directory from which the program is running. *USER\_NAME* is the operating +system's login user name. This user name could be different than the user's +principal name. For example, on Windows, the cache file could be +`C:\Windows\Users\duke\krb5cc_duke`, in which `duke` is the *USER\_NAME* and +`C:\Windows\Users\duke` is the *USER\_HOME*. + +By default, the keytab name is retrieved from the Kerberos configuration file. +If the keytab name isn't specified in the Kerberos configuration file, the +kinit tool assumes that the name is *USER\_HOME*`\krb5.keytab` + +If you don't specify the password using the *password* option on the command +line, the `kinit` tool prompts you for the password. + +**Note:** + +The `password` option is provided only for testing purposes. Don't specify your +password in a script or provide your password on the command line. Doing so +will compromise your password. + +## Commands + +You can specify one of the following commands. After the command, specify the +options for it. + +`-A` +: Doesn't include addresses. + +`-f` +: Issues a forwardable ticket. + +`-p` +: Issues a proxiable ticket. + +`-c` *cache\_name* +: The cache name (for example, `FILE:D:\temp\mykrb5cc`). + +`-l` *lifetime* +: Sets the lifetime of a ticket. The value can be one of "h:m[:s]", + "NdNhNmNs", and "N". See the [MIT krb5 Time Duration definition]( + http://web.mit.edu/kerberos/krb5-1.17/doc/basic/date_format.html#duration) + for more information. + +`-r` *renewable\_time* +: Sets the total lifetime that a ticket can be renewed. + +`-R` +: Renews a ticket. + +`-k` +: Uses keytab + +`-t` *keytab\_filename* +: The keytab name (for example, `D:\winnt\profiles\duke\krb5.keytab`). + +*principal* +: The principal name (for example, `duke@example.com`). + +*password* +: The *principal*'s Kerberos password. **Don't specify this on the command + line or in a script.** + +Run `kinit -help` to display the instructions above. + +## Examples + +Requests credentials valid for authentication from the current client host, for +the default services, storing the credentials cache in the default location +(`C:\Windows\Users\duke\krb5cc_duke`): + +> `kinit duke@example.com` + +Requests proxiable credentials for a different principal and store these +credentials in a specified file cache: + +> `kinit -l 1h -r 10h duke@example.com` + +Requests a TGT for the specified principal that will expire in 1 hour but +is renewable for up to 10 hours. Users must renew a ticket before it has +expired. The renewed ticket can be renewed repeatedly within 10 hours +from its initial request. + +> `kinit -R duke@example.com` + +Renews an existing renewable TGT for the specified principal. + +> `kinit -p -c FILE:C:\Windows\Users\duke\credentials\krb5cc_cafebeef + cafebeef@example.com` + +Requests proxiable and forwardable credentials for a different principal and +stores these credentials in a specified file cache: + +> `kinit -f -p -c FILE:C:\Windows\Users\duke\credentials\krb5cc_cafebeef + cafebeef@example.com` + +Displays the help menu for the `kinit` tool: + +> `kinit -help` diff --git a/src/java.security.jgss/windows/man/klist.md b/src/java.security.jgss/windows/man/klist.md new file mode 100644 index 00000000000..be9e26abe0f --- /dev/null +++ b/src/java.security.jgss/windows/man/klist.md @@ -0,0 +1,98 @@ +--- +# Copyright (c) 2005, 2018, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'KLIST(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +klist - display the entries in the local credentials cache and key table + +## Synopsis + +`klist` \[`-c` \[`-f`\] \[`-e`\] \[`-a` \[`-n`\]\]\] \[`-k` \[`-t`\] \[`-K`\]\] +\[*name*\] \[`-help`\] + +## Description + +The `klist` tool displays the entries in the local credentials cache and key +table. After you modify the credentials cache with the `kinit` tool or modify +the keytab with the `ktab` tool, the only way to verify the changes is to view +the contents of the credentials cache or keytab using the `klist` tool. The +`klist` tool doesn't change the Kerberos database. + +## Commands + +`-c` +: Specifies that the credential cache is to be listed. + + The following are the options for credential cache entries: + + `-f` + : Show credential flags. + + `-e` + : Show the encryption type. + + `-a` + : Show addresses. + + `-n` + : If the `-a` option is specified, don't reverse resolve addresses. + +`-k` +: Specifies that key tab is to be listed. + + List the keytab entries. The following are the options for keytab entries: + + `-t` + : Show keytab entry timestamps. + + `-K` + : Show keytab entry DES keys. + + `-e` + : Shows keytab entry key type. + +*name* +: Specifies the credential cache name or the keytab name. File-based cache or + keytab's prefix is `FILE:`. If the name isn't specified, the `klist` tool + uses default values for the cache name and keytab. The `kinit` + documentation lists these default values. + +`-help` +: Displays instructions. + +## Examples + +List entries in the keytable specified including keytab entry timestamps and +DES keys: + +> `klist -k -t -K FILE:\temp\mykrb5cc` + +List entries in the credentials cache specified including credentials flag and +address list: + +> `klist -c -f FILE:\temp\mykrb5cc` diff --git a/src/java.security.jgss/windows/man/ktab.md b/src/java.security.jgss/windows/man/ktab.md new file mode 100644 index 00000000000..ac8a6d4a0ec --- /dev/null +++ b/src/java.security.jgss/windows/man/ktab.md @@ -0,0 +1,134 @@ +--- +# Copyright (c) 2005, 2022, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'KTAB(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +ktab - manage the principal names and service keys stored in a local key +table + +## Synopsis + +`ktab` \[*commands*\] \[*options*\] + +\[*commands*\] \[*options*\] +: Lists the keytab name and entries, adds new key entries to the keytab, + deletes existing key entries, and displays instructions. See [Commands and + Options]. + +## Description + +The `ktab` enables the user to manage the principal names and service keys +stored in a local key table. Principal and key pairs listed in the keytab +enable services running on a host to authenticate themselves to the Key +Distribution Center (KDC). + +Before configuring a server to use Kerberos, you must set up a keytab on the +host running the server. Note that any updates made to the keytab using the +`ktab` tool don't affect the Kerberos database. + +A *keytab* is a host's copy of its own keylist, which is analogous to a user's +password. An application server that needs to authenticate itself to the Key +Distribution Center (KDC) must have a keytab which contains its own principal +and key. If you change the keys in the keytab, you must also make the +corresponding changes to the Kerberos database. The `ktab` tool enables you to +list, add, update or delete principal names and key pairs in the key table. +None of these operations affect the Kerberos database. + +## Security Alert + +Don't specify your password on the command line. Doing so can be a security +risk. For example, an attacker could discover your password while running the +UNIX `ps` command. + +Just as it is important for users to protect their passwords, it is equally +important for hosts to protect their keytabs. You should always store keytab +files on the local disk and make them readable only by root. You should never +send a keytab file over a network in the clear. + +## Commands and Options + +`-l` \[`-e`\] \[`-t`\] +: Lists the keytab name and entries. When `-e` is specified, the encryption + type for each entry is displayed. When `-t` is specified, the timestamp for + each entry is displayed. + +`-a` *principal\_name* \[*password*\] \[`-n` *kvno*\] \[`-s` *salt* \| `-f`\] \[`-append`\] +: Adds new key entries to the keytab for the given principal name with an + optional *password*. If a *kvno* is specified, new keys' Key Version + Numbers equal to the value, otherwise, automatically incrementing the Key + Version Numbers. If *salt* is specified, it will be used instead of the + default salt. If `-f` is specified, the KDC will be contacted to + fetch the salt. If `-append` is specified, new keys are appended to the + keytab, otherwise, old keys for the same principal are removed. + + No changes are made to the Kerberos database. **Don't specify the password + on the command line or in a script.** This tool will prompt for a password + if it isn't specified. + +`-d` *principal\_name* \[`-f`\] \[`-e` *etype*\] \[*kvno* \| `all`\| `old`\] +: Deletes key entries from the keytab for the specified principal. No changes + are made to the Kerberos database. + + - If *kvno* is specified, the tool deletes keys whose Key Version Numbers + match kvno. If `all` is specified, delete all keys. + + - If `old` is specified, the tool deletes all keys except those with the + highest *kvno*. The default action is `all`. + + - If *etype* is specified, the tool only deletes keys of this encryption + type. *etype* should be specified as the numeric value *etype* defined + in RFC 3961, section 8. A prompt to confirm the deletion is displayed + unless `-f` is specified. + + When *etype* is provided, only the entry matching this encryption type is + deleted. Otherwise, all entries are deleted. + +`-help` +: Displays instructions. + +## Common Options + +This option can be used with the `-l`, `-a` or `-d` commands. + +`-k` *keytab name* +: Specifies the keytab name and path with the `FILE:` prefix. + +## Examples + +- Lists all the entries in the default keytable + + > `ktab -l` + +- Adds a new principal to the key table (note that you will be prompted for + your password) + + > `ktab -a duke@example.com` + +- Deletes a principal from the key table + + > `ktab -d duke@example.com` diff --git a/src/jdk.accessibility/windows/man/jabswitch.md b/src/jdk.accessibility/windows/man/jabswitch.md new file mode 100644 index 00000000000..8dfdd6f2737 --- /dev/null +++ b/src/jdk.accessibility/windows/man/jabswitch.md @@ -0,0 +1,75 @@ +--- +# Copyright (c) 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JABSWITCH(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jabswitch - enable or disable the Java Access Bridge + +## Synopsis + +`jabswitch` \[ -enable|/enable | -disable|/disable | -version|/version | -?|/? \] + +## Options + +`-enable` +or +`/enable` +: Enables the Java Access Bridge + +`-disable` +or +`/disable` +: Disables the Java Access Bridge + +`-version` +or +`/version` +: Displays version information for the `jabswitch` command. + +`-?` +or +`/?` +: Displays usage information for the `jabswitch` command. + +## Description + +The `jabswitch` command is a utility program that enables the +Java Access Bridge to be loaded by the JDK on Windows platforms. +The Java Access Bridge is used by Assistive Technologies +to interact with Java Accessibility APIs of the Java SE platform. +To have any effect, the assistive technology must support the Java Access Bridge. + +This command creates or updates a file named `.accessibility.properties`, +in the user's home directory. When selecting the `-enable` option, the file +is populated with the information needed to load the Java Access Bridge. +This file is then read and used in accordance with the specification of the +Java SE +[`java.awt.Toolkit.getDefaultToolkit()`](../../api/java.desktop/java/awt/Toolkit.html#getDefaultToolkit()) +API, on initialization. + +Note: This command is only provided with JDK for Windows. diff --git a/src/jdk.accessibility/windows/man/jaccessinspector.md b/src/jdk.accessibility/windows/man/jaccessinspector.md new file mode 100644 index 00000000000..17f44cef358 --- /dev/null +++ b/src/jdk.accessibility/windows/man/jaccessinspector.md @@ -0,0 +1,249 @@ +--- +# Copyright (c) 2017, 2018, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JACCESSINSPECTOR(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jaccessinspector - examine accessible information about the objects in the +Java Virtual Machine using the Java Accessibility Utilities API + +## Description + +The `jaccessinspector` tool lets you select different methods for examining the +object accessibility information: + +- When events occur such as a change of focus, mouse movement, property + change, menu selection, and the display of a popup menu + +- When you press the F1 key when the mouse is over an object, or F2 when the + mouse is over a window + +After an object has been selected for examination, the `jaccessinspector` tool +displays the results of calling Java Accessibility API methods on that object. + +## Running the jaccessinspector Tool + +To use the `jaccessinspector` tool, launch the `jaccessinspector` tool after +launching a Java application. To launch `jaccessinspector`, run the following +command: + +**Note:** + +`JAVA_HOME` is an environment variable and should be set to the path of the JDK +or JRE, such as `c:\Program Files\Java\jdk-10`. + +> `%JAVA_HOME%\bin\jaccessinspector.exe` + +You now have two windows open: The Java application window and the +`jaccessinspector` window. The `jaccessinspector` window contains five menus: + +- [File Menu] + +- [UpdateSettings Menu] + +- [JavaEvents Menu] + +- [AccessibilityEvents Menu] + +- [Options Menu] + +The items in **UpdateSettings**, **JavaEvents**, and **AccessibilityEvents** +menus let you query Java applications in a variety of ways. + +## File Menu + +This section describes the **File** menu items. + +AccessBridge DLL Loaded +: Enables and disables AccessBridge DLL Loaded. + +Exit +: Exits from the tool. + +## UpdateSettings Menu + +This section describes the **UpdateSettings** menu items. + +Update from Mouse +: Determines the x- and y-coordinates of the mouse (assuming the + `jaccessinspector` tool window is topmost) when the mouse has stopped + moving, and then queries the Java application for the accessible object + underneath the mouse, dumping the output into the `jaccessinspector` + window. + +Update with F2 (Mouse HWND) +: Determines the x- and y-coordinates of the mouse (assuming the + `jaccessinspector` tool window is topmost), and then queries the Java + application for the accessible object of the HWND underneath the mouse, + dumping the output into the `jaccessinspector` window. + +Update with F1 (Mouse Point) +: Determines the x- and y-coordinates of the mouse (assuming the + `jaccessinspector` tool window is topmost), and then queries the Java + application for the accessible object underneath the cursor, dumping the + output into the `jaccessinspector` window. + +## JavaEvents Menu + +This section describes the **JavaEvents** menu items. + +Track Mouse Events +: Registers with the Java application all Java Mouse Entered events, and upon + receiving one, queries the object that was entered by the cursor and dumps + the output into the `jaccessinspector` window. + + **Note:** If the mouse is moved quickly, then there may be some delay + before the displayed information is updated. + +Track Focus Events +: Registers with the Java application all Java Focus Gained events, and upon + receiving an event, queries the object that received the focus and dumps + the output into the `jaccessinspector` window. + +Track Caret Events +: Register with the Java application all Java Caret Update events, and upon + receiving an event, queries the object in which the caret was updated, and + dumps the output into the `jaccessinspector` window. + + **Note:** Because objects that contain carets are almost by definition + objects that are rich text objects, this won't seem as responsive as the + other event tracking options. In real use, one would make fewer + accessibility calls in Caret Update situations (for example, just get the + new letter, word, sentence at the caret location), which would be + significantly faster. + +Track Menu Selected \| Deselected \| Cancelled Events +: Registers with the Java application all Menu events, and upon receiving an + event, queries the object in which the caret was updated, and dumps the + output into the `jaccessinspector` window. + +Track Popup Visible \| Invisible \| Cancelled Events +: Registers with the Java application all Popup Menu events, and upon + receiving an event, queries the object in which the caret was updated, and + dumps the output into the `jaccessinspector` window. + +Track Shutdown Events +: Registers with the Java application to receive a Property Changed event + when a Java application terminates. + +## AccessibilityEvents Menu + +This section describes the **AccessibilityEvents** menu items. + +**Note:** The items listed in the **AccessibilityEvents** menu are the most +important for testing applications, especially for assistive technology +applications. + +Track Name Property Events +: Registers with the Java application all Java Property Changed events + specifically on accessible objects in which the Name property has changed, + and upon receiving an event, dumps the output into the scrolling window, + along with information about the property that changed. + +Track Description Property Events +: Register with the Java application for all Java Property Changed events + specifically on accessible objects in which the Description property has + changed, and upon receiving an event, dumps the output into the + `jaccessinspector` window, along with information about the property that + changed. + +Track State Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the State property has changed, + and upon receiving an event, dumps the output into the `jaccessinspector` + window, along with information about the property that changed. + +Track Value Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Value property has changed, + and upon receiving an event, dumps the output into the scrolling window, + along with information about the property that changed. + +Track Selection Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Selection property has + changed, and upon receiving an event, dumps the output into the + `jaccessinspector` window, along with information about the property that + changed. + +Track Text Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Text property has changed, + and upon receiving one event, dump the output into the `jaccessinspector` + window, along with information about the property that changed. + +Track Caret Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Caret property has changed, + and upon receiving an event, dumps the output into the `jaccessinspector` + window, along with information about the property that changed. + +Track VisibleData Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the VisibleData property has + changed, and upon receiving an event, dumps the output into the + `jaccessinspector` window, along with information about the property that + changed. + +Track Child Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Child property has changed, + and upon receiving an event, dumps the output into the `jaccessinspector` + window, along with information about the property that changed. + +Track Active Descendent Property Events +: Register with the Java application all Java Property Changed events + specifically on accessible objects in which the Active Descendent property + has changed, and upon receiving an event, dumps the output into the + `jaccessinspector` window, along with information about the property that + changed. + +Track Table Model Change Property Events +: Register with the Java application all Property Changed events specifically + on accessible objects in which the Table Model Change property has changed, + and upon receiving an event, dumps the output into the `jaccessinspector` + window, along with information about the property that changed. + +## Options Menu + +This section describes the **Options** menu items. + +Monitor the same events as JAWS +: Enables monitoring of only the events also monitored by JAWS. + +Monitor All Events +: Enables monitoring of all events in the `jaccessinspector` window. + +Reset All Events +: Resets the selected Options to the default settings. + +Go To Message +: Opens the **Go To Message** dialog that lets you display a logged message + by entering its message number. + +Clear Message History +: Clears the history of logged messages from the `jaccessinspector` window. diff --git a/src/jdk.accessibility/windows/man/jaccesswalker.md b/src/jdk.accessibility/windows/man/jaccesswalker.md new file mode 100644 index 00000000000..f688ae57aee --- /dev/null +++ b/src/jdk.accessibility/windows/man/jaccesswalker.md @@ -0,0 +1,71 @@ +--- +# Copyright (c) 2017, 2018, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JACCESSWALKER(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jaccesswalker - navigate through the component trees in a particular Java +Virtual Machine and present the hierarchy in a tree view + +## Description + +You select a node in the tree, and from the **Panels** menu, you select +**Accessibility API Panel**. The `jaccesswalker` tool shows you the +accessibility information for the object in the window. + +## Running the jaccesswalker Tool + +To use `jaccesswalker`, launch the `jaccesswalker` tool after launching a Java +application. For example, to launch `jaccesswalker`, enter the following +command: + +**Note:** + +`JAVA_HOME` is an environment variable and should be set to the path of the JDK +or JRE, such as, `c:\Program Files\Java\jdk-10`. + +> `%JAVA_HOME%\bin\jaccesswalker.exe` + +You now have two windows open: The Java application window, and the window for +the `jaccesswalker` tool. There are two tasks that you can do with +`jaccesswalker` . You can build a tree view of the Java applications' GUI +hierarchy, and you can query the Java Accessibility API information of a +particular element in the GUI hierarchy. + +## Building the GUI Hierarchy + +From the **File** menu, select **Refresh Tree** menu. The `jaccesswalker` tool +builds a list of the top-level windows belonging to Java applications. The tool +then recursively queries the elements in those windows, and builds a tree of +all of the GUI components in all of the Java applications in all of the JVMs +running in the system. + +## Examining a GUI Component + +After a GUI tree is built, you can view detailed accessibility information +about an individual GUI component by selecting it in the tree, then selecting +**Panels**, and then **Display Accessibility Information**. diff --git a/src/jdk.compiler/share/man/javac.1 b/src/jdk.compiler/share/man/javac.1 deleted file mode 100644 index ebee0369238..00000000000 --- a/src/jdk.compiler/share/man/javac.1 +++ /dev/null @@ -1,2372 +0,0 @@ -.\" Copyright (c) 1994, 2023, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JAVAC" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -javac - read Java declarations and compile them into class files -.SH SYNOPSIS -.PP -\f[V]javac\f[R] [\f[I]options\f[R]] -[\f[I]sourcefiles-or-classnames\f[R]] -.TP -\f[I]options\f[R] -Command-line options. -.TP -\f[I]sourcefiles-or-classnames\f[R] -Source files to be compiled (for example, \f[V]Shape.java\f[R]) or the -names of previously compiled classes to be processed for annotations -(for example, \f[V]geometry.MyShape\f[R]). -.SH DESCRIPTION -.PP -The \f[V]javac\f[R] command reads \f[I]source files\f[R] that contain -module, package and type declarations written in the Java programming -language, and compiles them into \f[I]class files\f[R] that run on the -Java Virtual Machine. -.PP -The \f[V]javac\f[R] command can also \f[B]process annotations\f[R] in -Java source files and classes. -.PP -Source files must have a file name extension of \f[V].java\f[R]. -Class files have a file name extension of \f[V].class\f[R]. -Both source and class files normally have file names that identify the -contents. -For example, a class called \f[V]Shape\f[R] would be declared in a -source file called \f[V]Shape.java\f[R], and compiled into a class file -called \f[V]Shape.class\f[R]. -.PP -There are two ways to specify source files to \f[V]javac\f[R]: -.IP \[bu] 2 -For a small number of source files, you can list their file names on the -command line. -.IP \[bu] 2 -For a large number of source files, you can use the -\f[B]\f[VB]\[at]\f[B]\f[BI]filename\f[B]\f[R] option on the command line -to specify an \f[I]argument file\f[R] that lists their file names. -See \f[B]Standard Options\f[R] for a description of the option and -\f[B]Command-Line Argument Files\f[R] for a description of -\f[V]javac\f[R] argument files. -.PP -The order of source files specified on the command line or in an -argument file is not important. -\f[V]javac\f[R] will compile the files together, as a group, and will -automatically resolve any dependencies between the declarations in the -various source files. -.PP -\f[V]javac\f[R] expects that source files are arranged in one or more -directory hierarchies on the file system, described in \f[B]Arrangement -of Source Code\f[R]. -.PP -To compile a source file, \f[V]javac\f[R] needs to find the declaration -of every class or interface that is used, extended, or implemented by -the code in the source file. -This lets \f[V]javac\f[R] check that the code has the right to access -those classes and interfaces. -Rather than specifying the source files of those classes and interfaces -explicitly, you can use command-line options to tell \f[V]javac\f[R] -where to search for their source files. -If you have compiled those source files previously, you can use options -to tell \f[V]javac\f[R] where to search for the corresponding class -files. -The options, which all have names ending in \[dq]path\[dq], are -described in \f[B]Standard Options\f[R], and further described in -\f[B]Configuring a Compilation\f[R] and \f[B]Searching for Module, -Package and Type Declarations\f[R]. -.PP -By default, \f[V]javac\f[R] compiles each source file to a class file in -the same directory as the source file. -However, it is recommended to specify a separate destination directory -with the \f[B]\f[VB]-d\f[B]\f[R] option. -.PP -Command-line \f[B]options\f[R] and \f[B]environment variables\f[R] also -control how \f[V]javac\f[R] performs various tasks: -.IP \[bu] 2 -Compiling code to run on earlier releases of the JDK. -.IP \[bu] 2 -Compiling code to run under a debugger. -.IP \[bu] 2 -Checking for stylistic issues in Java source code. -.IP \[bu] 2 -Checking for problems in \f[V]javadoc\f[R] comments -(\f[V]/** ... */\f[R]). -.IP \[bu] 2 -Processing annotations in source files and class files. -.IP \[bu] 2 -Upgrading and patching modules in the compile-time environment. -.PP -\f[V]javac\f[R] supports \f[B]Compiling for Earlier Releases Of The -Platform\f[R] and can also be invoked from Java code using one of a -number of \f[B]APIs\f[R] -.SH OPTIONS -.PP -\f[V]javac\f[R] provides \f[B]standard options\f[R], and \f[B]extra -options\f[R] that are either non-standard or are for advanced use. -.PP -Some options take one or more arguments. -If an argument contains spaces or other whitespace characters, the value -should be quoted according to the conventions of the environment being -used to invoke javac. -If the option begins with a single dash (\f[V]-\f[R]) the argument -should either directly follow the option name, or should be separated -with a colon (\f[V]:\f[R]) or whitespace, depending on the option. -If the option begins with a double dash (\f[V]--\f[R]), the argument may -be separated either by whitespace or by an equals (\f[V]=\f[R]) -character with no additional whitespace. -For example, -.IP -.nf -\f[CB] --Aname=\[dq]J. Duke\[dq] --proc:only --d myDirectory ---module-version 3 ---module-version=3 -\f[R] -.fi -.PP -In the following lists of options, an argument of \f[I]path\f[R] -represents a search path, composed of a list of file system locations -separated by the platform path separator character, (semicolon -\f[V];\f[R] on Windows, or colon \f[V]:\f[R] on other systems.) -Depending on the option, the file system locations may be directories, -JAR files or JMOD files. -.SS Standard Options -.TP -\f[V]\[at]\f[R]\f[I]filename\f[R] -Reads options and file names from a file. -To shorten or simplify the \f[V]javac\f[R] command, you can specify one -or more files that contain arguments to the \f[V]javac\f[R] command -(except \f[B]\f[VB]-J\f[B]\f[R] options). -This lets you to create \f[V]javac\f[R] commands of any length on any -operating system. -See \f[B]Command-Line Argument Files\f[R]. -.TP -\f[V]-A\f[R]\f[I]key\f[R][\f[V]=\f[R]\f[I]value\f[R]] -Specifies options to pass to annotation processors. -These options are not interpreted by \f[V]javac\f[R] directly, but are -made available for use by individual processors. -The \f[I]key\f[R] value should be one or more identifiers separated by a -dot (\f[V].\f[R]). -.TP -\f[V]--add-modules\f[R] \f[I]module\f[R]\f[V],\f[R]\f[I]module\f[R] -Specifies root modules to resolve in addition to the initial modules, or -all modules on the module path if \f[I]module\f[R] is -\f[V]ALL-MODULE-PATH\f[R]. -.TP -\f[V]--boot-class-path\f[R] \f[I]path\f[R] or \f[V]-bootclasspath\f[R] \f[I]path\f[R] -Overrides the location of the bootstrap class files. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -For JDK 9 or later, see \f[B]\f[VB]--system\f[B]\f[R]. -.RE -.TP -\f[V]--class-path\f[R] \f[I]path\f[R], \f[V]-classpath\f[R] \f[I]path\f[R], or \f[V]-cp\f[R] \f[I]path\f[R] -Specifies where to find user class files and annotation processors. -This class path overrides the user class path in the \f[V]CLASSPATH\f[R] -environment variable. -.RS -.IP \[bu] 2 -If \f[V]--class-path\f[R], \f[V]-classpath\f[R], or \f[V]-cp\f[R] are -not specified, then the user class path is the value of the -\f[V]CLASSPATH\f[R] environment variable, if that is set, or else the -current directory. -.IP \[bu] 2 -If not compiling code for modules, if the -\f[B]\f[VB]--source-path\f[B]\f[R] or -sourcepath\[ga] option is not -specified, then the user class path is also searched for source files. -.IP \[bu] 2 -If the \f[B]\f[VB]-processorpath\f[B]\f[R] option is not specified, then -the class path is also searched for annotation processors. -.RE -.TP -\f[V]-d\f[R] \f[I]directory\f[R] -Sets the destination directory (or \f[I]class output directory\f[R]) for -class files. -If a class is part of a package, then \f[V]javac\f[R] puts the class -file in a subdirectory that reflects the module name (if appropriate) -and package name. -The directory, and any necessary subdirectories, will be created if they -do not already exist. -.RS -.PP -If the \f[V]-d\f[R] option is not specified, then \f[V]javac\f[R] puts -each class file in the same directory as the source file from which it -was generated. -.PP -Except when compiling code for multiple modules, the contents of the -class output directory will be organized in a package hierarchy. -When compiling code for multiple modules, the contents of the output -directory will be organized in a module hierarchy, with the contents of -each module in a separate subdirectory, each organized as a package -hierarchy. -.PP -\f[B]Note:\f[R] When compiling code for one or more modules, the class -output directory will automatically be checked when searching for -previously compiled classes. -When not compiling for modules, for backwards compatibility, the -directory is \f[I]not\f[R] automatically checked for previously compiled -classes, and so it is recommended to specify the class output directory -as one of the locations on the user class path, using the -\f[V]--class-path\f[R] option or one of its alternate forms. -.RE -.TP -\f[V]-deprecation\f[R] -Shows a description of each use or override of a deprecated member or -class. -Without the \f[V]-deprecation\f[R] option, \f[V]javac\f[R] shows a -summary of the source files that use or override deprecated members or -classes. -The \f[V]-deprecation\f[R] option is shorthand for -\f[V]-Xlint:deprecation\f[R]. -.TP -\f[V]--enable-preview\f[R] -Enables preview language features. -Used in conjunction with either \f[B]\f[VB]-source\f[B]\f[R] or -\f[B]\f[VB]--release\f[B]\f[R]. -.TP -\f[V]-encoding\f[R] \f[I]encoding\f[R] -Specifies character encoding used by source files, such as EUC-JP and -UTF-8. -If the \f[V]-encoding\f[R] option is not specified, then the platform -default converter is used. -.TP -\f[V]-endorseddirs\f[R] \f[I]directories\f[R] -Overrides the location of the endorsed standards path. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-extdirs\f[R] \f[I]directories\f[R] -Overrides the location of the installed extensions. -\f[V]directories\f[R] is a list of directories, separated by the -platform path separator (\f[V];\f[R] on Windows, and \f[V]:\f[R] -otherwise). -Each JAR file in the specified directories is searched for class files. -All JAR files found become part of the class path. -.RS -.PP -If you are compiling for a release of the platform that supports the -Extension Mechanism, then this option specifies the directories that -contain the extension classes. -See [Compiling for Other Releases of the Platform]. -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-g\f[R] -Generates all debugging information, including local variables. -By default, only line number and source file information is generated. -.TP -\f[V]-g:\f[R][\f[V]lines\f[R], \f[V]vars\f[R], \f[V]source\f[R]] -Generates only the kinds of debugging information specified by the -comma-separated list of keywords. -Valid keywords are: -.RS -.TP -\f[V]lines\f[R] -Line number debugging information. -.TP -\f[V]vars\f[R] -Local variable debugging information. -.TP -\f[V]source\f[R] -Source file debugging information. -.RE -.TP -\f[V]-g:none\f[R] -Does not generate debugging information. -.TP -\f[V]-h\f[R] \f[I]directory\f[R] -Specifies where to place generated native header files. -.RS -.PP -When you specify this option, a native header file is generated for each -class that contains native methods or that has one or more constants -annotated with the \f[B]\f[VB]java.lang.annotation.Native\f[B]\f[R] -annotation. -If the class is part of a package, then the compiler puts the native -header file in a subdirectory that reflects the module name (if -appropriate) and package name. -The directory, and any necessary subdirectories, will be created if they -do not already exist. -.RE -.TP -\f[V]--help\f[R], \f[V]-help\f[R] or \f[V]-?\f[R] -Prints a synopsis of the standard options. -.TP -\f[V]--help-extra\f[R] or \f[V]-X\f[R] -Prints a synopsis of the set of extra options. -.TP -\f[V]--help-lint\f[R] -Prints the supported keys for the \f[V]-Xlint\f[R] option. -.TP -\f[V]-implicit:\f[R][\f[V]none\f[R], \f[V]class\f[R]] -Specifies whether or not to generate class files for implicitly -referenced files: -.RS -.IP \[bu] 2 -\f[V]-implicit:class\f[R] --- Automatically generates class files. -.IP \[bu] 2 -\f[V]-implicit:none\f[R] --- Suppresses class file generation. -.PP -If this option is not specified, then the default automatically -generates class files. -In this case, the compiler issues a warning if any class files are -generated when also doing annotation processing. -The warning is not issued when the \f[V]-implicit\f[R] option is -explicitly set. -See \f[B]Searching for Module, Package and Type Declarations\f[R]. -.RE -.TP -\f[V]-J\f[R]\f[I]option\f[R] -Passes \f[I]option\f[R] to the runtime system, where \f[I]option\f[R] is -one of the Java options described on \f[B]java\f[R] command. -For example, \f[V]-J-Xms48m\f[R] sets the startup memory to 48 MB. -.RS -.PP -\f[B]Note:\f[R] The \f[V]CLASSPATH\f[R] environment variable, -\f[V]-classpath\f[R] option, \f[V]-bootclasspath\f[R] option, and -\f[V]-extdirs\f[R] option do not specify the classes used to run -\f[V]javac\f[R]. -Trying to customize the compiler implementation with these options and -variables is risky and often does not accomplish what you want. -If you must customize the compiler implementation, then use the -\f[V]-J\f[R] option to pass options through to the underlying Java -launcher. -.RE -.TP -\f[V]--limit-modules\f[R] \f[I]module\f[R]\f[V],\f[R]\f[I]module\f[R]* -Limits the universe of observable modules. -.TP -\f[V]--module\f[R] \f[I]module-name\f[R] (\f[V],\f[R]\f[I]module-name\f[R])* or \f[V]-m\f[R] \f[I]module-name\f[R] (\f[V],\f[R]\f[I]module-name\f[R])* -Compiles those source files in the named modules that are newer than the -corresponding files in the output directory. -.TP -\f[V]--module-path\f[R] \f[I]path\f[R] or \f[V]-p\f[R] \f[I]path\f[R] -Specifies where to find application modules. -.TP -\f[V]--module-source-path\f[R] \f[I]module-source-path\f[R] -Specifies where to find source files when compiling code in multiple -modules. -See [Compilation Modes] and \f[B]The Module Source Path Option\f[R]. -.TP -\f[V]--module-version\f[R] \f[I]version\f[R] -Specifies the version of modules that are being compiled. -.TP -\f[V]-nowarn\f[R] -Disables warning messages. -This option operates the same as the \f[V]-Xlint:none\f[R] option. -.TP -\f[V]-parameters\f[R] -Generates metadata for reflection on method parameters. -Stores formal parameter names of constructors and methods in the -generated class file so that the method -\f[V]java.lang.reflect.Executable.getParameters\f[R] from the Reflection -API can retrieve them. -.TP -\f[V]-proc:\f[R][\f[V]none\f[R], \f[V]only\f[R], \f[V]full\f[R]] -Controls whether annotation processing and compilation are done. -\f[V]-proc:none\f[R] means that compilation takes place without -annotation processing. -\f[V]-proc:only\f[R] means that only annotation processing is done, -without any subsequent compilation. -If this option is not used, or \f[V]-proc:full\f[R] is specified, -annotation processing and compilation are done. -.TP -\f[V]-processor\f[R] \f[I]class1\f[R][\f[V],\f[R]\f[I]class2\f[R]\f[V],\f[R]\f[I]class3\f[R]...] -Names of the annotation processors to run. -This bypasses the default discovery process. -.TP -\f[V]--processor-module-path\f[R] \f[I]path\f[R] -Specifies the module path used for finding annotation processors. -.TP -\f[V]--processor-path\f[R] \f[I]path\f[R] or \f[V]-processorpath\f[R] \f[I]path\f[R] -Specifies where to find annotation processors. -If this option is not used, then the class path is searched for -processors. -.TP -\f[V]-profile\f[R] \f[I]profile\f[R] -Checks that the API used is available in the specified profile. -This option is deprecated and may be removed in a future release. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]--release\f[R] \f[I]release\f[R] -Compiles source code according to the rules of the Java programming -language for the specified Java SE release, generating class files which -target that release. -Source code is compiled against the combined Java SE and JDK API for the -specified release. -.RS -.PP -The supported values of \f[I]release\f[R] are the current Java SE -release and a limited number of previous releases, detailed in the -command-line help. -.PP -For the current release, the Java SE API consists of the -\f[V]java.*\f[R], \f[V]javax.*\f[R], and \f[V]org.*\f[R] packages that -are exported by the Java SE modules in the release; the JDK API consists -of the \f[V]com.*\f[R] and \f[V]jdk.*\f[R] packages that are exported by -the JDK modules in the release, plus the \f[V]javax.*\f[R] packages that -are exported by standard, but non-Java SE, modules in the release. -.PP -For previous releases, the Java SE API and the JDK API are as defined in -that release. -.PP -\f[B]Note:\f[R] When using \f[V]--release\f[R], you cannot also use the -\f[B]\f[VB]--source\f[B]\f[R]/\f[V]-source\f[R] or -\f[B]\f[VB]--target\f[B]\f[R]/\f[V]-target\f[R] options. -.PP -\f[B]Note:\f[R] When using \f[V]--release\f[R] to specify a release that -supports the Java Platform Module System, the \f[V]--add-exports\f[R] -option cannot be used to enlarge the set of packages exported by the -Java SE, JDK, and standard modules in the specified release. -.RE -.TP -\f[V]-s\f[R] \f[I]directory\f[R] -Specifies the directory used to place the generated source files. -If a class is part of a package, then the compiler puts the source file -in a subdirectory that reflects the module name (if appropriate) and -package name. -The directory, and any necessary subdirectories, will be created if they -do not already exist. -.RS -.PP -Except when compiling code for multiple modules, the contents of the -source output directory will be organized in a package hierarchy. -When compiling code for multiple modules, the contents of the source -output directory will be organized in a module hierarchy, with the -contents of each module in a separate subdirectory, each organized as a -package hierarchy. -.RE -.TP -\f[V]--source\f[R] \f[I]release\f[R] or \f[V]-source\f[R] \f[I]release\f[R] -Compiles source code according to the rules of the Java programming -language for the specified Java SE release. -The supported values of \f[I]release\f[R] are the current Java SE -release and a limited number of previous releases, detailed in the -command-line help. -.RS -.PP -If the option is not specified, the default is to compile source code -according to the rules of the Java programming language for the current -Java SE release. -.RE -.TP -\f[V]--source-path\f[R] \f[I]path\f[R] or \f[V]-sourcepath\f[R] \f[I]path\f[R] -Specifies where to find source files. -Except when compiling multiple modules together, this is the source code -path used to search for class or interface definitions. -.RS -.PP -\f[B]Note:\f[R] Classes found through the class path might be recompiled -when their source files are also found. -See \f[B]Searching for Module, Package and Type Declarations\f[R]. -.RE -.TP -\f[V]--system\f[R] \f[I]jdk\f[R] | \f[V]none\f[R] -Overrides the location of system modules. -.TP -\f[V]--target\f[R] \f[I]release\f[R] or \f[V]-target\f[R] \f[I]release\f[R] -Generates \f[V]class\f[R] files suitable for the specified Java SE -release. -The supported values of \f[I]release\f[R] are the current Java SE -release and a limited number of previous releases, detailed in the -command-line help. -.RS -.PP -\f[B]Note:\f[R] The target release must be equal to or higher than the -source release. -(See \f[B]\f[VB]--source\f[B]\f[R].) -.RE -.TP -\f[V]--upgrade-module-path\f[R] \f[I]path\f[R] -Overrides the location of upgradeable modules. -.TP -\f[V]-verbose\f[R] -Outputs messages about what the compiler is doing. -Messages include information about each class loaded and each source -file compiled. -.TP -\f[V]--version\f[R] or \f[V]-version\f[R] -Prints version information. -.TP -\f[V]-Werror\f[R] -Terminates compilation when warnings occur. -.SS Extra Options -.TP -\f[V]--add-exports\f[R] \f[I]module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]other-module\f[R](\f[V],\f[R]\f[I]other-module\f[R])* -Specifies a package to be considered as exported from its defining -module to additional modules or to all unnamed modules when the value of -\f[I]other-module\f[R] is \f[V]ALL-UNNAMED\f[R]. -.TP -\f[V]--add-reads\f[R] \f[I]module\f[R]\f[V]=\f[R]\f[I]other-module\f[R](\f[V],\f[R]\f[I]other-module\f[R])* -Specifies additional modules to be considered as required by a given -module. -.TP -\f[V]--default-module-for-created-files\f[R] \f[I]module-name\f[R] -Specifies the fallback target module for files created by annotation -processors, if none is specified or inferred. -.TP -\f[V]--disable-line-doc-comments\f[R] -Disables support for documentation comments with lines beginning ///. -.TP -\f[V]-Djava.endorsed.dirs=\f[R]\f[I]dirs\f[R] -Overrides the location of the endorsed standards path. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-Djava.ext.dirs=\f[R]\f[I]dirs\f[R] -Overrides the location of installed extensions. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]--patch-module\f[R] \f[I]module\f[R]\f[V]=\f[R]\f[I]path\f[R] -Overrides or augments a module with classes and resources in JAR files -or directories. -.TP -\f[V]-Xbootclasspath:\f[R]\f[I]path\f[R] -Overrides the location of the bootstrap class files. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-Xbootclasspath/a:\f[R]\f[I]path\f[R] -Adds a suffix to the bootstrap class path. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-Xbootclasspath/p:\f[R]\f[I]path\f[R] -Adds a prefix to the bootstrap class path. -.RS -.PP -\f[B]Note:\f[R] This can only be used when compiling for releases prior -to JDK 9. -As applicable, see the descriptions in \f[B]\f[VB]--release\f[B]\f[R], -\f[B]\f[VB]-source\f[B]\f[R], or \f[B]\f[VB]-target\f[B]\f[R] for -details. -.RE -.TP -\f[V]-Xdiags:\f[R][\f[V]compact\f[R], \f[V]verbose\f[R]] -Selects a diagnostic mode. -.TP -\f[V]-Xdoclint\f[R] -Enables recommended checks for problems in documentation comments. -.TP -\f[V]-Xdoclint:\f[R](\f[V]all\f[R]|\f[V]none\f[R]|[\f[V]-\f[R]]\f[I]group\f[R])[\f[V]/\f[R]\f[I]access\f[R]] -Enables or disables specific groups of checks in documentation comments. -.RS -.PP -\f[I]group\f[R] can have one of the following values: -\f[V]accessibility\f[R], \f[V]html\f[R], \f[V]missing\f[R], -\f[V]reference\f[R], \f[V]syntax\f[R]. -.PP -The variable \f[I]access\f[R] specifies the minimum visibility level of -classes and members that the \f[V]-Xdoclint\f[R] option checks. -It can have one of the following values (in order of most to least -visible): \f[V]public\f[R], \f[V]protected\f[R], \f[V]package\f[R], -\f[V]private\f[R]. -.PP -The default \f[I]access\f[R] level is \f[V]private\f[R]. -.PP -When prefixed by \f[V]doclint:\f[R], the \f[I]group\f[R] names and -\f[V]all\f[R] can be used with \f[V]\[at]SuppressWarnings\f[R] to -suppress warnings about documentation comments in parts of the code -being compiled. -.PP -For more information about these groups of checks, see the -\f[B]DocLint\f[R] section of the \f[V]javadoc\f[R] command -documentation. -The \f[V]-Xdoclint\f[R] option is disabled by default in the -\f[V]javac\f[R] command. -.PP -For example, the following option checks classes and members (with all -groups of checks) that have the access level of protected and higher -(which includes protected and public): -.RS -.PP -\f[V]-Xdoclint:all/protected\f[R] -.RE -.PP -The following option enables all groups of checks for all access levels, -except it will not check for HTML errors for classes and members that -have the access level of package and higher (which includes package, -protected and public): -.RS -.PP -\f[V]-Xdoclint:all,-html/package\f[R] -.RE -.RE -.TP -\f[V]-Xdoclint/package:\f[R][\f[V]-\f[R]]\f[I]packages\f[R](\f[V],\f[R][\f[V]-\f[R]]\f[I]package\f[R])* -Enables or disables checks in specific packages. -Each \f[I]package\f[R] is either the qualified name of a package or a -package name prefix followed by \f[V].*\f[R], which expands to all -sub-packages of the given package. -Each \f[I]package\f[R] can be prefixed with a hyphen (\f[V]-\f[R]) to -disable checks for a specified package or packages. -.RS -.PP -For more information, see the \f[B]DocLint\f[R] section of the -\f[V]javadoc\f[R] command documentation. -.RE -.TP -\f[V]-Xlint\f[R] -Enables all recommended warnings. -In this release, enabling all available warnings is recommended. -.TP -\f[V]-Xlint:\f[R][\f[V]-\f[R]]\f[I]key\f[R](\f[V],\f[R][\f[V]-\f[R]]\f[I]key\f[R])* -Supplies warnings to enable or disable, separated by comma. -Precede a key by a hyphen (\f[V]-\f[R]) to disable the specified -warning. -.RS -.PP -Supported values for \f[I]key\f[R] are: -.IP \[bu] 2 -\f[V]all\f[R]: Enables all warnings. -.IP \[bu] 2 -\f[V]auxiliaryclass\f[R]: Warns about an auxiliary class that is hidden -in a source file, and is used from other files. -.IP \[bu] 2 -\f[V]cast\f[R]: Warns about the use of unnecessary casts. -.IP \[bu] 2 -\f[V]classfile\f[R]: Warns about the issues related to classfile -contents. -.IP \[bu] 2 -\f[V]dangling-doc-comments\f[R]: Warns about extra or misplaced -documentation comments near the beginning of a declaration. -.IP \[bu] 2 -\f[V]deprecation\f[R]: Warns about the use of deprecated items. -.IP \[bu] 2 -\f[V]dep-ann\f[R]: Warns about the items marked as deprecated in -\f[V]javadoc\f[R] but without the \f[V]\[at]Deprecated\f[R] annotation. -.IP \[bu] 2 -\f[V]divzero\f[R]: Warns about the division by the constant integer 0. -.IP \[bu] 2 -\f[V]empty\f[R]: Warns about an empty statement after \f[V]if\f[R]. -.IP \[bu] 2 -\f[V]exports\f[R]: Warns about the issues regarding module exports. -.IP \[bu] 2 -\f[V]fallthrough\f[R]: Warns about the falling through from one case of -a switch statement to the next. -.IP \[bu] 2 -\f[V]finally\f[R]: Warns about \f[V]finally\f[R] clauses that do not -terminate normally. -.IP \[bu] 2 -\f[V]incubating\f[R]: Warns about the use of incubating modules. -.IP \[bu] 2 -\f[V]lossy-conversions\f[R]: Warns about possible lossy conversions in -compound assignment. -.IP \[bu] 2 -\f[V]missing-explicit-ctor\f[R]: Warns about missing explicit -constructors in public and protected classes in exported packages. -.IP \[bu] 2 -\f[V]module\f[R]: Warns about the module system-related issues. -.IP \[bu] 2 -\f[V]opens\f[R]: Warns about the issues related to module opens. -.IP \[bu] 2 -\f[V]options\f[R]: Warns about the issues relating to use of command -line options. -.IP \[bu] 2 -\f[V]output-file-clash\f[R]: Warns if any output file is overwritten -during compilation. -This can occur, for example, on case-insensitive filesystems. -.IP \[bu] 2 -\f[V]overloads\f[R]: Warns about the issues related to method overloads. -.IP \[bu] 2 -\f[V]overrides\f[R]: Warns about the issues related to method overrides. -.IP \[bu] 2 -\f[V]path\f[R]: Warns about the invalid path elements on the command -line. -.IP \[bu] 2 -\f[V]preview\f[R]: Warns about the use of preview language features. -.IP \[bu] 2 -\f[V]processing\f[R]: Warns about the issues related to annotation -processing. -.IP \[bu] 2 -\f[V]rawtypes\f[R]: Warns about the use of raw types. -.IP \[bu] 2 -\f[V]removal\f[R]: Warns about the use of an API that has been marked -for removal. -.IP \[bu] 2 -\f[V]restricted\f[R]: Warns about the use of restricted methods. -.IP \[bu] 2 -\f[V]requires-automatic\f[R]: Warns developers about the use of -automatic modules in requires clauses. -.IP \[bu] 2 -\f[V]requires-transitive-automatic\f[R]: Warns about automatic modules -in requires transitive. -.IP \[bu] 2 -\f[V]serial\f[R]: Warns about the serializable classes that do not -provide a serial version ID. -Also warns about access to non-public members from a serializable -element. -.IP \[bu] 2 -\f[V]static\f[R]: Warns about the accessing a static member using an -instance. -.IP \[bu] 2 -\f[V]strictfp\f[R]: Warns about unnecessary use of the -\f[V]strictfp\f[R] modifier. -.IP \[bu] 2 -\f[V]synchronization\f[R]: Warns about synchronization attempts on -instances of value-based classes. -.IP \[bu] 2 -\f[V]text-blocks\f[R]: Warns about inconsistent white space characters -in text block indentation. -.IP \[bu] 2 -\f[V]this-escape\f[R]: Warns about constructors leaking \f[V]this\f[R] -prior to subclass initialization. -.IP \[bu] 2 -\f[V]try\f[R]: Warns about the issues relating to the use of try blocks -(that is, try-with-resources). -.IP \[bu] 2 -\f[V]unchecked\f[R]: Warns about the unchecked operations. -.IP \[bu] 2 -\f[V]varargs\f[R]: Warns about the potentially unsafe \f[V]vararg\f[R] -methods. -.IP \[bu] 2 -\f[V]none\f[R]: Disables all warnings. -.PP -With the exception of \f[V]all\f[R] and \f[V]none\f[R], the keys can be -used with the \f[V]\[at]SuppressWarnings\f[R] annotation to suppress -warnings in a part of the source code being compiled. -.PP -See \f[B]Examples of Using -Xlint keys\f[R]. -.RE -.TP -\f[V]-Xmaxerrs\f[R] \f[I]number\f[R] -Sets the maximum number of errors to print. -.TP -\f[V]-Xmaxwarns\f[R] \f[I]number\f[R] -Sets the maximum number of warnings to print. -.TP -\f[V]-Xpkginfo:\f[R][\f[V]always\f[R], \f[V]legacy\f[R], \f[V]nonempty\f[R]] -Specifies when and how the \f[V]javac\f[R] command generates -\f[V]package-info.class\f[R] files from \f[V]package-info.java\f[R] -files using one of the following options: -.RS -.TP -\f[V]always\f[R] -Generates a \f[V]package-info.class\f[R] file for every -\f[V]package-info.java\f[R] file. -This option may be useful if you use a build system such as Ant, which -checks that each \f[V].java\f[R] file has a corresponding -\f[V].class\f[R] file. -.TP -\f[V]legacy\f[R] -Generates a \f[V]package-info.class\f[R] file only if -\f[V]package-info.java\f[R] contains annotations. -This option does not generate a \f[V]package-info.class\f[R] file if -\f[V]package-info.java\f[R] contains only comments. -.RS -.PP -\f[B]Note:\f[R] A \f[V]package-info.class\f[R] file might be generated -but be empty if all the annotations in the \f[V]package-info.java\f[R] -file have \f[V]RetentionPolicy.SOURCE\f[R]. -.RE -.TP -\f[V]nonempty\f[R] -Generates a \f[V]package-info.class\f[R] file only if -\f[V]package-info.java\f[R] contains annotations with -\f[V]RetentionPolicy.CLASS\f[R] or \f[V]RetentionPolicy.RUNTIME\f[R]. -.RE -.TP -\f[V]-Xplugin:\f[R]\f[I]name\f[R] \f[I]args\f[R] -Specifies the name and optional arguments for a plug-in to be run. -If \f[I]args\f[R] are provided, \f[I]name\f[R] and \f[I]args\f[R] should -be quoted or otherwise escape the whitespace characters between the name -and all the arguments. -For details on the API for a plugin, see the API documentation for -\f[B]jdk.compiler/com.sun.source.util.Plugin\f[R]. -.TP -\f[V]-Xprefer:\f[R][\f[V]source\f[R], \f[V]newer\f[R]] -Specifies which file to read when both a source file and class file are -found for an implicitly compiled class using one of the following -options. -See \f[B]Searching for Module, Package and Type Declarations\f[R]. -.RS -.IP \[bu] 2 -\f[V]-Xprefer:newer\f[R]: Reads the newer of the source or class files -for a type (default). -.IP \[bu] 2 -\f[V]-Xprefer:source\f[R] : Reads the source file. -Use \f[V]-Xprefer:source\f[R] when you want to be sure that any -annotation processors can access annotations declared with a retention -policy of \f[V]SOURCE\f[R]. -.RE -.TP -\f[V]-Xprint\f[R] -Prints a textual representation of specified types for debugging -purposes. -This does not perform annotation processing or compilation. -The format of the output could change. -.TP -\f[V]-XprintProcessorInfo\f[R] -Prints information about which annotations a processor is asked to -process. -.TP -\f[V]-XprintRounds\f[R] -Prints information about initial and subsequent annotation processing -rounds. -.TP -\f[V]-Xstdout\f[R] \f[I]filename\f[R] -Sends compiler messages to the named file. -By default, compiler messages go to \f[V]System.err\f[R]. -.SH ENVIRONMENT VARIABLES -.SS CLASSPATH -.PP -If the \f[B]\f[VB]--class-path\f[B]\f[R] option or any of its alternate -forms are not specified, the class path will default to the value of the -\f[V]CLASSPATH\f[R] environment variable if it is set. -However, it is recommended that this environment variable should -\f[I]not\f[R] be set, and that the \f[V]--class-path\f[R] option should -be used to provide an explicit value for the class path when one is -required. -.SS JDK_JAVAC_OPTIONS -.PP -The content of the \f[V]JDK_JAVAC_OPTIONS\f[R] environment variable, -separated by white-spaces ( ) or white-space characters -(\f[V]\[rs]n\f[R], \f[V]\[rs]t\f[R], \f[V]\[rs]r\f[R], or -\f[V]\[rs]f\f[R]) is prepended to the command line arguments passed to -\f[V]javac\f[R] as a list of arguments. -.PP -The encoding requirement for the environment variable is the same as the -\f[V]javac\f[R] command line on the system. -\f[V]JDK_JAVAC_OPTIONS\f[R] environment variable content is treated in -the same manner as that specified in the command line. -.PP -Single quotes (\f[V]\[aq]\f[R]) or double quotes (\f[V]\[dq]\f[R]) can -be used to enclose arguments that contain whitespace characters. -All content between the open quote and the first matching close quote -are preserved by simply removing the pair of quotes. -In case a matching quote is not found, the launcher will abort with an -error message. -\f[V]\[at]\f[R]\f[I]files\f[R] are supported as they are specified in -the command line. -However, as in \f[V]\[at]\f[R]\f[I]files\f[R], use of a wildcard is not -supported. -.PP -\f[B]Examples of quoting arguments containing white spaces:\f[R] -.RS -.PP -\f[V]export JDK_JAVAC_OPTIONS=\[aq]\[at]\[dq]C:\[rs]white spaces\[rs]argfile\[dq]\[aq]\f[R] -.RE -.RS -.PP -\f[V]export JDK_JAVAC_OPTIONS=\[aq]\[dq]\[at]C:\[rs]white spaces\[rs]argfile\[dq]\[aq]\f[R] -.RE -.RS -.PP -\f[V]export JDK_JAVAC_OPTIONS=\[aq]\[at]C:\[rs]\[dq]white spaces\[dq]\[rs]argfile\[aq]\f[R] -.RE -.SH COMMAND-LINE ARGUMENT FILES -.PP -An argument file can include command-line options and source file names -in any combination. -The arguments within a file can be separated by spaces or new line -characters. -If a file name contains embedded spaces, then put the whole file name in -double quotation marks. -.PP -File names within an argument file are relative to the current -directory, not to the location of the argument file. -Wildcards (\f[V]*\f[R]) are not allowed in these lists (such as for -specifying \f[V]*.java\f[R]). -Use of the at sign (\f[V]\[at]\f[R]) to recursively interpret files is -not supported. -The \f[V]-J\f[R] options are not supported because they\[aq]re passed to -the launcher, which does not support argument files. -.PP -When executing the \f[V]javac\f[R] command, pass in the path and name of -each argument file with the at sign (\f[V]\[at]\f[R]) leading character. -When the \f[V]javac\f[R] command encounters an argument beginning with -the at sign (\f[V]\[at]\f[R]), it expands the contents of that file into -the argument list. -.SS Examples of Using javac \[at]filename -.TP -Single Argument File -You could use a single argument file named \f[V]argfile\f[R] to hold all -\f[V]javac\f[R] arguments: -.RS -.RS -.PP -\f[V]javac \[at]argfile\f[R] -.RE -.PP -This argument file could contain the contents of both files shown in the -following \f[B]Two Argument Files\f[R] example. -.RE -.TP -Two Argument Files -You can create two argument files: one for the \f[V]javac\f[R] options -and the other for the source file names. -Note that the following lists have no line-continuation characters. -.RS -.PP -Create a file named \f[V]options\f[R] that contains the following: -.PP -\f[B]Linux and macOS:\f[R] -.IP -.nf -\f[CB] --d classes --g --sourcepath /java/pubs/ws/1.3/src/share/classes -\f[R] -.fi -.PP -\f[B]Windows:\f[R] -.IP -.nf -\f[CB] --d classes --g --sourcepath C:\[rs]java\[rs]pubs\[rs]ws\[rs]1.3\[rs]src\[rs]share\[rs]classes -\f[R] -.fi -.PP -Create a file named \f[V]sources\f[R] that contains the following: -.IP -.nf -\f[CB] -MyClass1.java -MyClass2.java -MyClass3.java -\f[R] -.fi -.PP -Then, run the \f[V]javac\f[R] command as follows: -.RS -.PP -\f[V]javac \[at]options \[at]sources\f[R] -.RE -.RE -.TP -Argument Files with Paths -The argument files can have paths, but any file names inside the files -are relative to the current working directory (not \f[V]path1\f[R] or -\f[V]path2\f[R]): -.RS -.RS -.PP -\f[V]javac \[at]path1/options \[at]path2/sources\f[R] -.RE -.RE -.SH ARRANGEMENT OF SOURCE CODE -.PP -In the Java language, classes and interfaces can be organized into -packages, and packages can be organized into modules. -\f[V]javac\f[R] expects that the physical arrangement of source files in -directories of the file system will mirror the organization of classes -into packages, and packages into modules. -.PP -It is a widely adopted convention that module names and package names -begin with a lower-case letter, and that class names begin with an -upper-case letter. -.SS Arrangement of Source Code for a Package -.PP -When classes and interfaces are organized into a package, the package is -represented as a directory, and any subpackages are represented as -subdirectories. -.PP -For example: -.IP \[bu] 2 -The package \f[V]p\f[R] is represented as a directory called -\f[V]p\f[R]. -.IP \[bu] 2 -The package \f[V]p.q\f[R] -- that is, the subpackage \f[V]q\f[R] of -package \f[V]p\f[R] -- is represented as the subdirectory \f[V]q\f[R] of -directory \f[V]p\f[R]. -The directory tree representing package \f[V]p.q\f[R] is therefore -\f[V]p\[rs]q\f[R] on Windows, and \f[V]p/q\f[R] on other systems. -.IP \[bu] 2 -The package \f[V]p.q.r\f[R] is represented as the directory tree -\f[V]p\[rs]q\[rs]r\f[R] (on Windows) or \f[V]p/q/r\f[R] (on other -systems). -.PP -Within a directory or subdirectory, \f[V].java\f[R] files represent -classes and interfaces in the corresponding package or subpackage. -.PP -For example: -.IP \[bu] 2 -The class \f[V]X\f[R] declared in package \f[V]p\f[R] is represented by -the file \f[V]X.java\f[R] in the \f[V]p\f[R] directory. -.IP \[bu] 2 -The class \f[V]Y\f[R] declared in package \f[V]p.q\f[R] is represented -by the file \f[V]Y.java\f[R] in the \f[V]q\f[R] subdirectory of -directory \f[V]p\f[R]. -.IP \[bu] 2 -The class \f[V]Z\f[R] declared in package \f[V]p.q.r\f[R] is represented -by the file \f[V]Z.java\f[R] in the \f[V]r\f[R] subdirectory of -\f[V]p\[rs]q\f[R] (on Windows) or \f[V]p/q\f[R] (on other systems). -.PP -In some situations, it is convenient to split the code into separate -directories, each structured as described above, and the aggregate list -of directories specified to \f[V]javac\f[R]. -.SS Arrangement of Source Code for a Module -.PP -In the Java language, a module is a set of packages designed for reuse. -In addition to \f[V].java\f[R] files for classes and interfaces, each -module has a source file called \f[V]module-info.java\f[R] which: -.IP "1." 3 -declares the module\[aq]s name; -.IP "2." 3 -lists the packages exported by the module (to allow reuse by other -modules); -.IP "3." 3 -lists other modules required by the module (to reuse their exported -packages). -.PP -When packages are organized into a module, the module is represented by -one or more directories representing the packages in the module, one of -which contains the \f[V]module-info.java\f[R] file. -It may be convenient, but it is not required, to use a single directory, -named after the module, to contain the \f[V]module-info.java\f[R] file -alongside the directory tree which represents the packages in the module -(i.e., the \f[I]package hierarchy\f[R] described above). -The exact arrangement of source code for a module is typically dictated -by the conventions adopted by a development environment (IDE) or build -system. -.PP -For example: -.IP \[bu] 2 -The module \f[V]a.b.c\f[R] may be represented by the directory -\f[V]a.b.c\f[R], on all systems. -.IP \[bu] 2 -The module\[aq]s declaration is represented by the file -\f[V]module-info.java\f[R] in the \f[V]a.b.c\f[R] directory. -.IP \[bu] 2 -If the module contains package \f[V]p.q.r\f[R], then the \f[V]a.b.c\f[R] -directory contains the directory tree \f[V]p\[rs]q\[rs]r\f[R] (on -Windows) or \f[V]p/q/r\f[R] (on other systems). -.PP -The development environment may prescribe some directory hierarchy -between the directory named for the module and the source files to be -read by \f[V]javac\f[R]. -.PP -For example: -.IP \[bu] 2 -The module \f[V]a.b.c\f[R] may be represented by the directory -\f[V]a.b.c\f[R] -.IP \[bu] 2 -The module\[aq]s declaration and the module\[aq]s packages may be in -some subdirectory of \f[V]a.b.c\f[R], such as -\f[V]src\[rs]main\[rs]java\f[R] (on Windows) or \f[V]src/main/java\f[R] -(on other systems). -.SH CONFIGURING A COMPILATION -.PP -This section describes how to configure \f[V]javac\f[R] to perform a -basic compilation. -.PP -See \f[B]Configuring the Module System\f[R] for additional details for -use when compiling for a release of the platform that supports modules. -.SS Source Files -.IP \[bu] 2 -Specify the source files to be compiled on the command line. -.PP -If there are no compilation errors, the corresponding class files will -be placed in the \f[B]output directory\f[R]. -.PP -Some systems may limit the amount you can put on a command line; to work -around those limits, you can use \f[B]argument files\f[R]. -.PP -When compiling code for modules, you can also specify source files -indirectly, by using the \f[B]\f[VB]--module\f[B]\f[R] or \f[V]-m\f[R] -option. -.SS Output Directory -.IP \[bu] 2 -Use the \f[B]\f[VB]-d\f[B]\f[R] option to specify an output directory in -which to put the compiled class files. -.PP -This will normally be organized in a \f[B]package hierarchy\f[R], unless -you are compiling source code from multiple modules, in which case it -will be organized as a \f[B]module hierarchy\f[R]. -.PP -When the compilation has been completed, if you are compiling one or -more modules, you can place the output directory on the module path for -the Java \f[B]launcher\f[R]; otherwise, you can place the place the -output directory on the class path for the Java launcher. -.SS Precompiled Code -.PP -The code to be compiled may refer to libraries beyond what is provided -by the platform. -If so, you must place these libraries on the class path or module path. -If the library code is not in a module, place it on the class path; if -it is in a module, place it on the module path. -.IP \[bu] 2 -Use the \f[B]\f[VB]--class-path\f[B]\f[R] option to specify libraries to -be placed on the class path. -Locations on the class path should be organized in a \f[B]package -hierarchy\f[R]. -You can also use alternate forms of the option: \f[V]-classpath\f[R] or -\f[V]-cp\f[R]. -.IP \[bu] 2 -Use the \f[B]\f[VB]--module-path\f[B]\f[R] option to specify libraries -to be placed on the module path. -Locations on the module path should either be modules or directories of -modules. -You can also use an alternate form of the option: \f[V]-p\f[R]. -.RS 2 -.PP -See \f[B]Configuring the Module System\f[R] for details on how to modify -the default configuration of library modules. -.RE -.PP -\f[B]Note\f[R]: the options for the class path and module path are not -mutually exclusive, although it is not common to specify the class path -when compiling code for one or more modules. -.SS Additional Source Files -.PP -The code to be compiled may refer to types in additional source files -that are not specified on the command line. -If so, you must put those source files on either the source path or -module path. -You can only specify one of these options: if you are not compiling code -for a module, or if you are only compiling code for a single module, use -the source path; if you are compiling code for multiple modules, use the -module source path. -.IP \[bu] 2 -Use the \f[B]\f[VB]--source-path\f[B]\f[R] option to specify the -locations of additional source files that may be read by javac. -Locations on the source path should be organized in a \f[B]package -hierarchy\f[R]. -You can also use an alternate form of the option: \f[V]-sourcepath\f[R]. -.IP \[bu] 2 -Use the \f[B]\f[VB]--module-source-path\f[B]\f[R] option one or more -times to specify the location of additional source files in different -modules that may be read by javac, or when compiling source files in -multiple modules. -You can either specify the locations for each module -\f[B]individually\f[R], or you can organize the source files so that you -can specify the locations all \f[B]together\f[R]. -For more details, see \f[B]The Module Source Path Option\f[R]. -.PP -If you want to be able to refer to types in additional source files but -do not want them to be compiled, use the \f[B]\f[VB]-implicit\f[B]\f[R] -option. -.PP -\f[B]Note\f[R]: if you are compiling code for multiple modules, you must -always specify a module source path, and all source files specified on -the command line must be in one of the directories on the module source -path, or in a subdirectory thereof. -.SS Example of Compiling Multiple Source Files -.PP -This example compiles the \f[V]Aloha.java\f[R], \f[V]GutenTag.java\f[R], -\f[V]Hello.java\f[R], and \f[V]Hi.java\f[R] source files in the -\f[V]greetings\f[R] package. -.PP -\f[B]Linux and macOS:\f[R] -.IP -.nf -\f[CB] -% javac greetings/*.java -% ls greetings -Aloha.class GutenTag.class Hello.class Hi.class -Aloha.java GutenTag.java Hello.java Hi.java -\f[R] -.fi -.PP -\f[B]Windows:\f[R] -.IP -.nf -\f[CB] -C:\[rs]>javac greetings\[rs]*.java -C:\[rs]>dir greetings -Aloha.class GutenTag.class Hello.class Hi.class -Aloha.java GutenTag.java Hello.java Hi.java -\f[R] -.fi -.SS Example of Specifying a User Class Path -.PP -After changing one of the source files in the previous example, -recompile it: -.PP -\f[B]Linux and macOS:\f[R] -.IP -.nf -\f[CB] -pwd -/examples -javac greetings/Hi.java -\f[R] -.fi -.PP -\f[B]Windows:\f[R] -.IP -.nf -\f[CB] -C:\[rs]>cd -\[rs]examples -C:\[rs]>javac greetings\[rs]Hi.java -\f[R] -.fi -.PP -Because \f[V]greetings.Hi\f[R] refers to other classes in the -\f[V]greetings\f[R] package, the compiler needs to find these other -classes. -The previous example works because the default user class path is the -directory that contains the package directory. -If you want to recompile this file without concern for which directory -you are in, then add the examples directory to the user class path by -setting \f[V]CLASSPATH\f[R]. -This example uses the \f[V]-classpath\f[R] option. -.PP -\f[B]Linux and macOS:\f[R] -.RS -.PP -\f[V]javac -classpath /examples /examples/greetings/Hi.java\f[R] -.RE -.PP -\f[B]Windows:\f[R] -.RS -.PP -\f[V]C:\[rs]>javac -classpath \[rs]examples \[rs]examples\[rs]greetings\[rs]Hi.java\f[R] -.RE -.PP -If you change \f[V]greetings.Hi\f[R] to use a banner utility, then that -utility also needs to be accessible through the user class path. -.PP -\f[B]Linux and macOS:\f[R] -.IP -.nf -\f[CB] -javac -classpath /examples:/lib/Banners.jar \[rs] - /examples/greetings/Hi.java -\f[R] -.fi -.PP -\f[B]Windows:\f[R] -.IP -.nf -\f[CB] -C:\[rs]>javac -classpath \[rs]examples;\[rs]lib\[rs]Banners.jar \[ha] - \[rs]examples\[rs]greetings\[rs]Hi.java -\f[R] -.fi -.PP -To execute a class in the \f[V]greetings\f[R] package, the program needs -access to the \f[V]greetings\f[R] package, and to the classes that the -\f[V]greetings\f[R] classes use. -.PP -\f[B]Linux and macOS:\f[R] -.RS -.PP -\f[V]java -classpath /examples:/lib/Banners.jar greetings.Hi\f[R] -.RE -.PP -\f[B]Windows:\f[R] -.RS -.PP -\f[V]C:\[rs]>java -classpath \[rs]examples;\[rs]lib\[rs]Banners.jar greetings.Hi\f[R] -.RE -.SH CONFIGURING THE MODULE SYSTEM -.PP -If you want to include additional modules in your compilation, use the -\f[B]\f[VB]--add-modules\f[B]\f[R] option. -This may be necessary when you are compiling code that is not in a -module, or which is in an automatic module, and the code refers to API -in the additional modules. -.PP -If you want to restrict the set of modules in your compilation, use the -\f[B]\f[VB]--limit-modules\f[B]\f[R] option. -This may be useful if you want to ensure that the code you are compiling -is capable of running on a system with a limited set of modules -installed. -.PP -If you want to break encapsulation and specify that additional packages -should be considered as exported from a module, use the -\f[B]\f[VB]--add-exports\f[B]\f[R] option. -This may be useful when performing white-box testing; relying on access -to internal API in production code is strongly discouraged. -.PP -If you want to specify that additional packages should be considered as -required by a module, use the \f[B]\f[VB]--add-reads\f[B]\f[R] option. -This may be useful when performing white-box testing; relying on access -to internal API in production code is strongly discouraged. -.PP -You can patch additional content into any module using the -\f[B]\f[VB]--patch-module\f[B]\f[R] option. -See [Patching a Module] for more details. -.SH SEARCHING FOR MODULE, PACKAGE AND TYPE DECLARATIONS -.PP -To compile a source file, the compiler often needs information about a -module or type, but the declaration is not in the source files specified -on the command line. -.PP -\f[V]javac\f[R] needs type information for every class or interface -used, extended, or implemented in the source file. -This includes classes and interfaces not explicitly mentioned in the -source file, but that provide information through inheritance. -.PP -For example, when you create a subclass of \f[V]java.awt.Window\f[R], -you are also using the ancestor classes of \f[V]Window\f[R]: -\f[V]java.awt.Container\f[R], \f[V]java.awt.Component\f[R], and -\f[V]java.lang.Object\f[R]. -.PP -When compiling code for a module, the compiler also needs to have -available the declaration of that module. -.PP -A successful search may produce a class file, a source file, or both. -If both are found, then you can use the \f[B]\f[VB]-Xprefer\f[B]\f[R] -option to instruct the compiler which to use. -.PP -If a search finds and uses a source file, then by default -\f[V]javac\f[R] compiles that source file. -This behavior can be altered with \f[B]\f[VB]-implicit\f[B]\f[R]. -.PP -The compiler might not discover the need for some type information until -after annotation processing completes. -When the type information is found in a source file and no -\f[B]\f[VB]-implicit\f[B]\f[R] option is specified, the compiler gives a -warning that the file is being compiled without being subject to -annotation processing. -To disable the warning, either specify the file on the command line (so -that it will be subject to annotation processing) or use the -\f[B]\f[VB]-implicit\f[B]\f[R] option to specify whether or not class -files should be generated for such source files. -.PP -The way that \f[V]javac\f[R] locates the declarations of those types -depends on whether the reference exists within code for a module or not. -.SS Searching Package Oriented Paths -.PP -When searching for a source or class file on a path composed of package -oriented locations, \f[V]javac\f[R] will check each location on the path -in turn for the possible presence of the file. -The first occurrence of a particular file shadows (hides) any subsequent -occurrences of like-named files. -This shadowing does not affect any search for any files with a different -name. -This can be convenient when searching for source files, which may be -grouped in different locations, such as shared code, platform-specific -code and generated code. -It can also be useful when injecting alternate versions of a class file -into a package, to debugging or other instrumentation reasons. -But, it can also be dangerous, such as when putting incompatible -different versions of a library on the class path. -.SS Searching Module Oriented Paths -.PP -Prior to scanning any module paths for any package or type declarations, -\f[V]javac\f[R] will lazily scan the following paths and locations to -determine the modules that will be used in the compilation. -.IP \[bu] 2 -The module source path (see the -\f[B]\f[VB]--module-source-path\f[B]\f[R] option) -.IP \[bu] 2 -The path for upgradeable modules (see the -\f[B]\f[VB]--upgrade-module-path\f[B]\f[R] option) -.IP \[bu] 2 -The system modules (see the \f[B]\f[VB]--system\f[B]\f[R] option) -.IP \[bu] 2 -The user module path ( see the \f[B]\f[VB]--module-path\f[B]\f[R] -option) -.PP -For any module, the first occurrence of the module during the scan -completely shadows (hides) any subsequent appearance of a like-named -module. -While locating the modules, \f[V]javac\f[R] is able to determine the -packages exported by the module and to associate with each module a -package oriented path for the contents of the module. -For any previously compiled module, this path will typically be a single -entry for either a directory or a file that provides an internal -directory-like hierarchy, such as a JAR file. -Thus, when searching for a type that is in a package that is known to be -exported by a module, \f[V]javac\f[R] can locate the declaration -directly and efficiently. -.SS Searching for the Declaration of a Module -.PP -If the module has been previously compiled, the module declaration is -located in a file named \f[V]module-info.class\f[R] in the root of the -package hierarchy for the content of the module. -.PP -If the module is one of those currently being compiled, the module -declaration will be either the file named \f[V]module-info.class\f[R] in -the root of the package hierarchy for the module in the class output -directory, or the file named \f[V]module-info.java\f[R] in one of the -locations on the source path or one the module source path for the -module. -.SS Searching for the Declaration of a Type When the Reference is not in a Module -.PP -When searching for a type that is referenced in code that is not in a -module, \f[V]javac\f[R] will look in the following places: -.IP \[bu] 2 -The platform classes (or the types in exported packages of the platform -modules) (This is for compiled class files only.) -.IP \[bu] 2 -Types in exported packages of any modules on the module path, if -applicable. -(This is for compiled class files only.) -.IP \[bu] 2 -Types in packages on the class path and/or source path: -.RS 2 -.IP \[bu] 2 -If both are specified, \f[V]javac\f[R] looks for compiled class files on -the class path and for source files on the source path. -.IP \[bu] 2 -If the class path is specified, but not source path, \f[V]javac\f[R] -looks for both compiled class files and source files on the class path. -.IP \[bu] 2 -If the class path is not specified, it defaults to the current -directory. -.RE -.PP -When looking for a type on the class path and/or source path, if both a -compiled class file and a source file are found, the most recently -modified file will be used by default. -If the source file is newer, it will be compiled and will may override -any previously compiled version of the file. -You can use the \f[B]\f[VB]-Xprefer\f[B]\f[R] option to override the -default behavior. -.SS Searching for the Declaration of a Type When the Reference is in a Module -.PP -When searching for a type that is referenced in code in a module, -\f[V]javac\f[R] will examine the declaration of the enclosing module to -determine if the type is in a package that is exported from another -module that is readable by the enclosing module. -If so, \f[V]javac\f[R] will simply and directly go to the definition of -that module to find the definition of the required type. -Unless the module is another of the modules being compiled, -\f[V]javac\f[R] will only look for compiled class files files. -In other words, \f[V]javac\f[R] will not look for source files in -platform modules or modules on the module path. -.PP -If the type being referenced is not in some other readable module, -\f[V]javac\f[R] will examine the module being compiled to try and find -the declaration of the type. -\f[V]javac\f[R] will look for the declaration of the type as follows: -.IP \[bu] 2 -Source files specified on the command line or on the source path or -module source path. -.IP \[bu] 2 -Previously compiled files in the output directory. -.SH DIRECTORY HIERARCHIES -.PP -\f[V]javac\f[R] generally assumes that source files and compiled class -files will be organized in a file system directory hierarchy or in a -type of file that supports in an internal directory hierarchy, such as a -JAR file. -Three different kinds of hierarchy are supported: a \f[I]package -hierarchy\f[R], a \f[I]module hierarchy\f[R], and a \f[I]module source -hierarchy\f[R]. -.PP -While \f[V]javac\f[R] is fairly relaxed about the organization of source -code, beyond the expectation that source will be organized in one or -package hierarchies, and can generally accommodate organizations -prescribed by development environments and build tools, Java tools in -general, and \f[V]javac\f[R] and the Java launcher in particular, are -more stringent regarding the organization of compiled class files, and -will be organized in package hierarchies or module hierarchies, as -appropriate. -.PP -The location of these hierarchies are specified to \f[V]javac\f[R] with -command-line options, whose names typically end in \[dq]path\[dq], like -\f[B]\f[VB]--source-path\f[B]\f[R] or \f[B]\f[VB]--class-path\f[B]\f[R]. -Also as a general rule, path options whose name includes the word -\f[V]module\f[R], like \f[B]\f[VB]--module-path\f[B]\f[R], are used to -specify module hierarchies, although some module-related path options -allow a package hierarchy to be specified on a per-module basis. -All other path options are used to specify package hierarchies. -.SS Package Hierarchy -.PP -In a package hierarchy, directories and subdirectories are used to -represent the component parts of the package name, with the source file -or compiled class file for a type being stored as a file with an -extension of \f[V].java\f[R] or \f[V].class\f[R] in the most nested -directory. -.PP -For example, in a package hierarchy, the source file for a class -\f[V]com.example.MyClass\f[R] will be stored in the file -\f[I]com/example/MyClass.java\f[R] -.SS Module Hierarchy -.PP -In a module hierarchy, the first level of directories are named for the -modules in the hierarchy; within each of those directories the contents -of the module are organized in package hierarchies. -.PP -For example, in a module hierarchy, the compiled class file for a type -called \f[V]com.example.MyClass\f[R] in a module called -\f[V]my.library\f[R] will be stored in -\f[I]my.library/com/example/MyClass.class\f[R]. -.PP -The various output directories used by \f[V]javac\f[R] (the class output -directory, the source output directory, and native header output -directory) will all be organized in a module hierarchy when multiple -modules are being compiled. -.SS Module Source Hierarchy -.PP -Although the source for each individual module should always be -organized in a package hierarchy, it may be convenient to group those -hierarchies into a module source hierarchy. -This is similar to a module hierarchy, except that there may be -intervening directories between the directory for the module and the -directory that is the root of the package hierarchy for the source code -of the module. -.PP -For example, in a module source hierarchy, the source file for a type -called \f[V]com.example.MyClass\f[R] in a module called -\f[V]my.library\f[R] may be stored in a file such as -\f[I]my.library/src/main/java/com/example/MyClass.java\f[R]. -.SH THE MODULE SOURCE PATH OPTION -.PP -The \f[B]\f[VB]--module-source-path\f[B]\f[R] option has two forms: a -\f[I]module-specific form\f[R], in which a package path is given for -each module containing code to be compiled, and a -\f[I]module-pattern\f[R] form, in which the source path for each module -is specified by a pattern. -The module-specific form is generally simpler to use when only a small -number of modules are involved; the module-pattern form may be more -convenient when the number of modules is large and the modules are -organized in a regular manner that can be described by a pattern. -.PP -Multiple instances of the \f[V]--module-source-path\f[R] option may be -given, each one using either the module-pattern form or the -module-specific form, subject to the following limitations: -.IP \[bu] 2 -the module-pattern form may be used at most once -.IP \[bu] 2 -the module-specific form may be used at most once for any given module -.PP -If the module-specific form is used for any module, the associated -search path overrides any path that might otherwise have been inferred -from the module-pattern form. -.SS Module-specific form -.PP -The module-specific form allows an explicit search path to be given for -any specific module. -This form is: -.IP \[bu] 2 -\f[V]--module-source-path\f[R] -\f[I]module-name\f[R]\f[V]=\f[R]\f[I]file-path\f[R] -(\f[I]path-separator\f[R] \f[I]file-path\f[R])* -.PP -The path separator character is \f[V];\f[R] on Windows, and \f[V]:\f[R] -otherwise. -.PP -\f[B]Note:\f[R] this is similar to the form used for the -\f[B]\f[VB]--patch-module\f[B]\f[R] option. -.SS Module-pattern form -.PP -The module-pattern form allows a concise specification of the module -source path for any number of modules organized in regular manner. -.IP \[bu] 2 -\f[V]--module-source-path\f[R] \f[I]pattern\f[R] -.PP -The pattern is defined by the following rules, which are applied in -order: -.IP \[bu] 2 -The argument is considered to be a series of segments separated by the -path separator character (\f[V];\f[R] on Windows, and \f[V]:\f[R] -otherwise). -.IP \[bu] 2 -Each segment containing curly braces of the form -.RS 2 -.IP -.nf -\f[CB] -string1{alt1 ( ,alt2 )* } string2 -\f[R] -.fi -.PP -is considered to be replaced by a series of segments formed by -\[dq]expanding\[dq] the braces: -.IP -.nf -\f[CB] -string1 alt1 string2 -string1 alt2 string2 -and so on... -\f[R] -.fi -.PP -The braces may be nested. -.PP -This rule is applied for all such usages of braces. -.RE -.IP \[bu] 2 -Each segment must have at most one asterisk (\f[V]*\f[R]). -If a segment does not contain an asterisk, it is considered to be as -though the file separator character and an asterisk are appended. -.RS 2 -.PP -For any module \f[I]M\f[R], the source path for that module is formed -from the series of segments obtained by substituting the module name -\f[I]M\f[R] for the asterisk in each segment. -.PP -\f[B]Note\f[R]: in this context, the asterisk is just used as a special -marker, to denote the position in the path of the module name. -It should not be confused with the use of \f[V]*\f[R] as a file name -wildcard character, as found on most operating systems. -.RE -.SH PATCHING MODULES -.PP -javac allows any content, whether in source or compiled form, to be -patched into any module using the \f[B]\f[VB]--patch-module\f[B]\f[R] -option. -You may want to do this to compile alternative implementations of a -class to be patched at runtime into a JVM, or to inject additional -classes into the module, such as when testing. -.PP -The form of the option is: -.IP \[bu] 2 -\f[V]--patch-module\f[R] -\f[I]module-name\f[R]\f[V]=\f[R]\f[I]file-path\f[R] -(\f[I]path-separator\f[R] \f[I]file-path\f[R] )* -.PP -The path separator character is \f[V];\f[R] on Windows, and \f[V]:\f[R] -otherwise. -The paths given for the module must specify the root of a package -hierarchy for the contents of the module -.PP -The option may be given at most once for any given module. -Any content on the path will hide any like-named content later in the -path and in the patched module. -.PP -When patching source code into more than one module, the -\f[B]\f[VB]--module-source-path\f[B]\f[R] must also be used, so that the -output directory is organized in a module hierarchy, and capable of -holding the compiled class files for the modules being compiled. -.SH ANNOTATION PROCESSING -.PP -The \f[V]javac\f[R] command provides direct support for annotation -processing. -.PP -The API for annotation processors is defined in the -\f[V]javax.annotation.processing\f[R] and \f[V]javax.lang.model\f[R] -packages and subpackages. -.SS How Annotation Processing Works -.PP -Unless annotation processing is disabled with the -\f[B]\f[VB]-proc:none\f[B]\f[R] option, the compiler searches for any -annotation processors that are available. -The search path can be specified with the -\f[B]\f[VB]-processorpath\f[B]\f[R] option. -If no path is specified, then the user class path is used. -Processors are located by means of service provider-configuration files -named \f[V]META-INF/services/javax.annotation.processing.Processor\f[R] -on the search path. -Such files should contain the names of any annotation processors to be -used, listed one per line. -Alternatively, processors can be specified explicitly, using the -\f[B]\f[VB]-processor\f[B]\f[R] option. -.PP -After scanning the source files and classes on the command line to -determine what annotations are present, the compiler queries the -processors to determine what annotations they process. -When a match is found, the processor is called. -A processor can claim the annotations it processes, in which case no -further attempt is made to find any processors for those annotations. -After all of the annotations are claimed, the compiler does not search -for additional processors. -.PP -If any processors generate new source files, then another round of -annotation processing occurs: Any newly generated source files are -scanned, and the annotations processed as before. -Any processors called on previous rounds are also called on all -subsequent rounds. -This continues until no new source files are generated. -.PP -After a round occurs where no new source files are generated, the -annotation processors are called one last time, to give them a chance to -complete any remaining work. -Finally, unless the \f[B]\f[VB]-proc:only\f[B]\f[R] option is used, the -compiler compiles the original and all generated source files. -.PP -If you use an annotation processor that generates additional source -files to be included in the compilation, you can specify a default -module to be used for the newly generated files, for use when a module -declaration is not also generated. -In this case, use the -\f[B]\f[VB]--default-module-for-created-files\f[B]\f[R] option. -.SS Compilation Environment and Runtime Environment. -.PP -The declarations in source files and previously compiled class files are -analyzed by \f[V]javac\f[R] in a \f[I]compilation environment\f[R] that -is distinct from the \f[I]runtime environment\f[R] used to execute -\f[V]javac\f[R] itself. -Although there is a deliberate similarity between many \f[V]javac\f[R] -options and like-named options for the Java \f[B]launcher\f[R], such as -\f[V]--class-path\f[R], \f[V]--module-path\f[R] and so on, it is -important to understand that in general the \f[V]javac\f[R] options just -affect the environment in which the source files are compiled, and do -not affect the operation of \f[V]javac\f[R] itself. -.PP -The distinction between the compilation environment and runtime -environment is significant when it comes to using annotation processors. -Although annotations processors process elements (declarations) that -exist in the compilation environment, the annotation processor itself is -executed in the runtime environment. -If an annotation processor has dependencies on libraries that are not in -modules, the libraries can be placed, along with the annotation -processor itself, on the processor path. -(See the \f[B]\f[VB]--processor-path\f[B]\f[R] option.) -If the annotation processor and its dependencies are in modules, you -should use the processor module path instead. -(See the \f[B]\f[VB]--processor-module-path\f[B]\f[R] option.) -When those are insufficient, it may be necessary to provide further -configuration of the runtime environment. -This can be done in two ways: -.IP "1." 3 -If \f[V]javac\f[R] is invoked from the command line, options can be -passed to the underlying runtime by prefixing the option with -\f[B]\f[VB]-J\f[B]\f[R]. -.IP "2." 3 -You can start an instance of a Java Virtual Machine directly and use -command line options and API to configure an environment in which -\f[V]javac\f[R] can be invoked via one of its \f[B]APIs\f[R]. -.SH COMPILING FOR EARLIER RELEASES OF THE PLATFORM -.PP -\f[V]javac\f[R] can compile code that is to be used on other releases of -the platform, using either the \f[B]\f[VB]--release\f[B]\f[R] option, or -the \f[B]\f[VB]--source\f[B]\f[R]/\f[V]-source\f[R] and -\f[B]\f[VB]--target\f[B]\f[R]/\f[V]-target\f[R] options, together with -additional options to specify the platform classes. -.PP -Depending on the desired platform release, there are some restrictions -on some of the options that can be used. -.IP \[bu] 2 -When compiling for JDK 8 and earlier releases, you cannot use any option -that is intended for use with the module system. -This includes all of the following options: -.RS 2 -.IP \[bu] 2 -\f[B]\f[VB]--module-source-path\f[B]\f[R], -\f[B]\f[VB]--upgrade-module-path\f[B]\f[R], -\f[B]\f[VB]--system\f[B]\f[R], \f[B]\f[VB]--module-path\f[B]\f[R], -\f[B]\f[VB]--add-modules\f[B]\f[R], \f[B]\f[VB]--add-exports\f[B]\f[R], -\f[V]--add-opens\f[R], \f[B]\f[VB]--add-reads\f[B]\f[R], -\f[B]\f[VB]--limit-modules\f[B]\f[R], -\f[B]\f[VB]--patch-module\f[B]\f[R] -.PP -If you use the \f[V]--source\f[R]/\f[V]-source\f[R] or -\f[V]--target\f[R]/\f[V]-target\f[R] options, you should also set the -appropriate platform classes using the boot class path family of -options. -.RE -.IP \[bu] 2 -When compiling for JDK 9 and later releases, you cannot use any option -that is intended to configure the boot class path. -This includes all of the following options: -.RS 2 -.IP \[bu] 2 -\f[B]\f[VB]-Xbootclasspath/p:\f[B]\f[R], -\f[B]\f[VB]-Xbootclasspath\f[B]\f[R], -\f[B]\f[VB]-Xbootclasspath/a:\f[B]\f[R], -\f[B]\f[VB]-endorseddirs\f[B]\f[R], -\f[B]\f[VB]-Djava.endorsed.dirs\f[B]\f[R], -\f[B]\f[VB]-extdirs\f[B]\f[R], \f[B]\f[VB]-Djava.ext.dirs\f[B]\f[R], -\f[B]\f[VB]-profile\f[B]\f[R] -.PP -If you use the \f[V]--source\f[R]/\f[V]-source\f[R] or -\f[V]--target\f[R]/\f[V]-target\f[R] options, you should also set the -appropriate platform classes using the \f[V]--system\f[R] option to give -the location of an appropriate installed release of JDK. -.RE -.PP -When using the \f[V]--release\f[R] option, only the supported documented -API for that release may be used; you cannot use any options to break -encapsulation to access any internal classes. -.SH APIS -.PP -The \f[V]javac\f[R] compiler can be invoked using an API in three -different ways: -.TP -The \f[B]Java Compiler API\f[R] -This provides the most flexible way to invoke the compiler, including -the ability to compile source files provided in memory buffers or other -non-standard file systems. -.TP -The \f[B]ToolProvider API\f[R] -A \f[V]ToolProvider\f[R] for \f[V]javac\f[R] can be obtained by calling -\f[V]ToolProvider.findFirst(\[dq]javac\[dq])\f[R]. -This returns an object with the equivalent functionality of the -command-line tool. -.RS -.PP -\f[B]Note\f[R]: This API should not be confused with the like-named API -in the \f[B]\f[VB]javax.tools\f[B]\f[R] package. -.RE -.TP -The \f[V]javac\f[R] \f[B]Legacy API\f[R] -This API is retained for backward compatibility only. -All new code should use either the Java Compiler API or the ToolProvider -API. -.PP -\f[B]Note:\f[R] All other classes and methods found in a package with -names that start with \f[V]com.sun.tools.javac\f[R] (subpackages of -\f[V]com.sun.tools.javac\f[R]) are strictly internal and subject to -change at any time. -.SH EXAMPLES OF USING -XLINT KEYS -.TP -\f[V]cast\f[R] -Warns about unnecessary and redundant casts, for example: -.RS -.RS -.PP -\f[V]String s = (String) \[dq]Hello!\[dq]\f[R] -.RE -.RE -.TP -\f[V]classfile\f[R] -Warns about issues related to class file contents. -.TP -\f[V]deprecation\f[R] -Warns about the use of deprecated items. -For example: -.RS -.IP -.nf -\f[CB] -java.util.Date myDate = new java.util.Date(); -int currentDay = myDate.getDay(); -\f[R] -.fi -.PP -The method \f[V]java.util.Date.getDay\f[R] has been deprecated since JDK -1.1. -.RE -.TP -\f[V]dep-ann\f[R] -Warns about items that are documented with the \f[V]\[at]deprecated\f[R] -Javadoc comment, but do not have the \f[V]\[at]Deprecated\f[R] -annotation, for example: -.RS -.IP -.nf -\f[CB] -/** - * \[at]deprecated As of Java SE 7, replaced by {\[at]link #newMethod()} - */ -public static void deprecatedMethod() { } -public static void newMethod() { } -\f[R] -.fi -.RE -.TP -\f[V]divzero\f[R] -Warns about division by the constant integer 0, for example: -.RS -.RS -.PP -\f[V]int divideByZero = 42 / 0;\f[R] -.RE -.RE -.TP -\f[V]empty\f[R] -Warns about empty statements after \f[V]if\f[R]statements, for example: -.RS -.IP -.nf -\f[CB] -class E { - void m() { - if (true) ; - } -} -\f[R] -.fi -.RE -.TP -\f[V]fallthrough\f[R] -Checks the switch blocks for fall-through cases and provides a warning -message for any that are found. -Fall-through cases are cases in a switch block, other than the last case -in the block, whose code does not include a \f[V]break\f[R] statement, -allowing code execution to fall through from that case to the next case. -For example, the code following the case 1 label in this switch block -does not end with a \f[V]break\f[R] statement: -.RS -.IP -.nf -\f[CB] -switch (x) { -case 1: - System.out.println(\[dq]1\[dq]); - // No break statement here. -case 2: - System.out.println(\[dq]2\[dq]); -} -\f[R] -.fi -.PP -If the \f[V]-Xlint:fallthrough\f[R] option was used when compiling this -code, then the compiler emits a warning about possible fall-through into -case, with the line number of the case in question. -.RE -.TP -\f[V]finally\f[R] -Warns about \f[V]finally\f[R] clauses that cannot be completed normally, -for example: -.RS -.IP -.nf -\f[CB] -public static int m() { - try { - throw new NullPointerException(); - } catch (NullPointerException(); { - System.err.println(\[dq]Caught NullPointerException.\[dq]); - return 1; - } finally { - return 0; - } - } -\f[R] -.fi -.PP -The compiler generates a warning for the \f[V]finally\f[R] block in this -example. -When the \f[V]int\f[R] method is called, it returns a value of 0. -A \f[V]finally\f[R] block executes when the \f[V]try\f[R] block exits. -In this example, when control is transferred to the \f[V]catch\f[R] -block, the \f[V]int\f[R] method exits. -However, the \f[V]finally\f[R] block must execute, so it\[aq]s executed, -even though control was transferred outside the method. -.RE -.TP -\f[V]options\f[R] -Warns about issues that related to the use of command-line options. -See \f[B]Compiling for Earlier Releases of the Platform\f[R]. -.TP -\f[V]overrides\f[R] -Warns about issues related to method overrides. -For example, consider the following two classes: -.RS -.IP -.nf -\f[CB] -public class ClassWithVarargsMethod { - void varargsMethod(String... s) { } -} - -public class ClassWithOverridingMethod extends ClassWithVarargsMethod { - \[at]Override - void varargsMethod(String[] s) { } -} -\f[R] -.fi -.PP -The compiler generates a warning similar to the following:. -.IP -.nf -\f[CB] -warning: [override] varargsMethod(String[]) in ClassWithOverridingMethod -overrides varargsMethod(String...) in ClassWithVarargsMethod; overriding -method is missing \[aq]...\[aq] -\f[R] -.fi -.PP -When the compiler encounters a \f[V]varargs\f[R] method, it translates -the \f[V]varargs\f[R] formal parameter into an array. -In the method \f[V]ClassWithVarargsMethod.varargsMethod\f[R], the -compiler translates the \f[V]varargs\f[R] formal parameter -\f[V]String... s\f[R] to the formal parameter \f[V]String[] s\f[R], an -array that matches the formal parameter of the method -\f[V]ClassWithOverridingMethod.varargsMethod\f[R]. -Consequently, this example compiles. -.RE -.TP -\f[V]path\f[R] -Warns about invalid path elements and nonexistent path directories on -the command line (with regard to the class path, the source path, and -other paths). -Such warnings cannot be suppressed with the -\f[V]\[at]SuppressWarnings\f[R] annotation. -For example: -.RS -.IP \[bu] 2 -\f[B]Linux and macOS:\f[R] -\f[V]javac -Xlint:path -classpath /nonexistentpath Example.java\f[R] -.IP \[bu] 2 -\f[B]Windows:\f[R] -\f[V]javac -Xlint:path -classpath C:\[rs]nonexistentpath Example.java\f[R] -.RE -.TP -\f[V]processing\f[R] -Warns about issues related to annotation processing. -The compiler generates this warning when you have a class that has an -annotation, and you use an annotation processor that cannot handle that -type of annotation. -For example, the following is a simple annotation processor: -.RS -.PP -\f[B]Source file AnnoProc.java\f[R]: -.IP -.nf -\f[CB] -import java.util.*; -import javax.annotation.processing.*; -import javax.lang.model.*; -import javax.lang.model.element.*; - -\[at]SupportedAnnotationTypes(\[dq]NotAnno\[dq]) -public class AnnoProc extends AbstractProcessor { - public boolean process(Set elems, RoundEnvironment renv){ - return true; - } - - public SourceVersion getSupportedSourceVersion() { - return SourceVersion.latest(); - } -} -\f[R] -.fi -.PP -\f[B]Source file AnnosWithoutProcessors.java\f[R]: -.IP -.nf -\f[CB] -\[at]interface Anno { } - -\[at]Anno -class AnnosWithoutProcessors { } -\f[R] -.fi -.PP -The following commands compile the annotation processor -\f[V]AnnoProc\f[R], then run this annotation processor against the -source file \f[V]AnnosWithoutProcessors.java\f[R]: -.IP -.nf -\f[CB] -javac AnnoProc.java -javac -cp . -Xlint:processing -processor AnnoProc -proc:only AnnosWithoutProcessors.java -\f[R] -.fi -.PP -When the compiler runs the annotation processor against the source file -\f[V]AnnosWithoutProcessors.java\f[R], it generates the following -warning: -.IP -.nf -\f[CB] -warning: [processing] No processor claimed any of these annotations: Anno -\f[R] -.fi -.PP -To resolve this issue, you can rename the annotation defined and used in -the class \f[V]AnnosWithoutProcessors\f[R] from \f[V]Anno\f[R] to -\f[V]NotAnno\f[R]. -.RE -.TP -\f[V]rawtypes\f[R] -Warns about unchecked operations on raw types. -The following statement generates a \f[V]rawtypes\f[R] warning: -.RS -.RS -.PP -\f[V]void countElements(List l) { ... }\f[R] -.RE -.PP -The following example does not generate a \f[V]rawtypes\f[R] warning: -.RS -.PP -\f[V]void countElements(List l) { ... }\f[R] -.RE -.PP -\f[V]List\f[R] is a raw type. -However, \f[V]List\f[R] is an unbounded wildcard parameterized type. -Because \f[V]List\f[R] is a parameterized interface, always specify its -type argument. -In this example, the \f[V]List\f[R] formal argument is specified with an -unbounded wildcard (\f[V]?\f[R]) as its formal type parameter, which -means that the \f[V]countElements\f[R] method can accept any -instantiation of the \f[V]List\f[R] interface. -.RE -.TP -\f[V]serial\f[R] -Warns about missing \f[V]serialVersionUID\f[R] definitions on -serializable classes. -For example: -.RS -.IP -.nf -\f[CB] -public class PersistentTime implements Serializable -{ - private Date time; - - public PersistentTime() { - time = Calendar.getInstance().getTime(); - } - - public Date getTime() { - return time; - } -} -\f[R] -.fi -.PP -The compiler generates the following warning: -.IP -.nf -\f[CB] -warning: [serial] serializable class PersistentTime has no definition of -serialVersionUID -\f[R] -.fi -.PP -If a serializable class does not explicitly declare a field named -\f[V]serialVersionUID\f[R], then the serialization runtime environment -calculates a default \f[V]serialVersionUID\f[R] value for that class -based on various aspects of the class, as described in the Java Object -Serialization Specification. -However, it\[aq]s strongly recommended that all serializable classes -explicitly declare \f[V]serialVersionUID\f[R] values because the default -process of computing \f[V]serialVersionUID\f[R] values is highly -sensitive to class details that can vary depending on compiler -implementations. -As a result, this might cause an unexpected -\f[V]InvalidClassExceptions\f[R] during deserialization. -To guarantee a consistent \f[V]serialVersionUID\f[R] value across -different Java compiler implementations, a serializable class must -declare an explicit \f[V]serialVersionUID\f[R] value. -.RE -.TP -\f[V]static\f[R] -Warns about issues relating to the use of static variables, for example: -.RS -.IP -.nf -\f[CB] -class XLintStatic { - static void m1() { } - void m2() { this.m1(); } -} -\f[R] -.fi -.PP -The compiler generates the following warning: -.IP -.nf -\f[CB] -warning: [static] static method should be qualified by type name, -XLintStatic, instead of by an expression -\f[R] -.fi -.PP -To resolve this issue, you can call the \f[V]static\f[R] method -\f[V]m1\f[R] as follows: -.RS -.PP -\f[V]XLintStatic.m1();\f[R] -.RE -.PP -Alternately, you can remove the \f[V]static\f[R] keyword from the -declaration of the method \f[V]m1\f[R]. -.RE -.TP -\f[V]this-escape\f[R] -Warns about constructors leaking \f[V]this\f[R] prior to subclass -initialization. -For example, this class: -.RS -.IP -.nf -\f[CB] -public class MyClass { - public MyClass() { - System.out.println(this.hashCode()); - } -} -\f[R] -.fi -.PP -generates the following warning: -.IP -.nf -\f[CB] -MyClass.java:3: warning: [this-escape] possible \[aq]this\[aq] escape - before subclass is fully initialized - System.out.println(this.hashCode()); - \[ha] -\f[R] -.fi -.PP -A \[aq]this\[aq] escape warning is generated when a constructor does -something that might result in a subclass method being invoked before -the constructor returns. -In such cases the subclass method would be operating on an incompletely -initialized instance. -In the above example, a subclass of \f[V]MyClass\f[R] that overrides -\f[V]hashCode()\f[R] to incorporate its own fields would likely produce -an incorrect result when invoked as shown. -.PP -Warnings are only generated if a subclass could exist that is outside of -the current module (or package, if no module) being compiled. -So, for example, constructors in final and non-public classes do not -generate warnings. -.RE -.TP -\f[V]try\f[R] -Warns about issues relating to the use of \f[V]try\f[R] blocks, -including try-with-resources statements. -For example, a warning is generated for the following statement because -the resource \f[V]ac\f[R] declared in the \f[V]try\f[R] block is not -used: -.RS -.IP -.nf -\f[CB] -try ( AutoCloseable ac = getResource() ) { // do nothing} -\f[R] -.fi -.RE -.TP -\f[V]unchecked\f[R] -Gives more detail for unchecked conversion warnings that are mandated by -the Java Language Specification, for example: -.RS -.IP -.nf -\f[CB] -List l = new ArrayList(); -List ls = l; // unchecked warning -\f[R] -.fi -.PP -During type erasure, the types \f[V]ArrayList\f[R] and -\f[V]List\f[R] become \f[V]ArrayList\f[R] and \f[V]List\f[R], -respectively. -.PP -The \f[V]ls\f[R] command has the parameterized type -\f[V]List\f[R]. -When the \f[V]List\f[R] referenced by \f[V]l\f[R] is assigned to -\f[V]ls\f[R], the compiler generates an unchecked warning. -At compile time, the compiler and JVM cannot determine whether -\f[V]l\f[R] refers to a \f[V]List\f[R] type. -In this case, \f[V]l\f[R] does not refer to a \f[V]List\f[R] -type. -As a result, heap pollution occurs. -.PP -A heap pollution situation occurs when the \f[V]List\f[R] object -\f[V]l\f[R], whose static type is \f[V]List\f[R], is assigned to -another \f[V]List\f[R] object, \f[V]ls\f[R], that has a different static -type, \f[V]List\f[R]. -However, the compiler still allows this assignment. -It must allow this assignment to preserve backward compatibility with -releases of Java SE that do not support generics. -Because of type erasure, \f[V]List\f[R] and -\f[V]List\f[R] both become \f[V]List\f[R]. -Consequently, the compiler allows the assignment of the object -\f[V]l\f[R], which has a raw type of \f[V]List\f[R], to the object -\f[V]ls\f[R]. -.RE -.TP -\f[V]varargs\f[R] -Warns about unsafe use of variable arguments (\f[V]varargs\f[R]) -methods, in particular, those that contain non-reifiable arguments, for -example: -.RS -.IP -.nf -\f[CB] -public class ArrayBuilder { - public static void addToList (List listArg, T... elements) { - for (T x : elements) { - listArg.add(x); - } - } -} -\f[R] -.fi -.PP -A non-reifiable type is a type whose type information is not fully -available at runtime. -.PP -The compiler generates the following warning for the definition of the -method \f[V]ArrayBuilder.addToList\f[R]: -.IP -.nf -\f[CB] -warning: [varargs] Possible heap pollution from parameterized vararg type T -\f[R] -.fi -.PP -When the compiler encounters a varargs method, it translates the -\f[V]varargs\f[R] formal parameter into an array. -However, the Java programming language does not permit the creation of -arrays of parameterized types. -In the method \f[V]ArrayBuilder.addToList\f[R], the compiler translates -the \f[V]varargs\f[R] formal parameter \f[V]T...\f[R] elements to the -formal parameter \f[V]T[]\f[R] elements, an array. -However, because of type erasure, the compiler converts the -\f[V]varargs\f[R] formal parameter to \f[V]Object[]\f[R] elements. -Consequently, there\[aq]s a possibility of heap pollution. -.RE diff --git a/src/jdk.compiler/share/man/javac.md b/src/jdk.compiler/share/man/javac.md new file mode 100644 index 00000000000..b41a395f386 --- /dev/null +++ b/src/jdk.compiler/share/man/javac.md @@ -0,0 +1,1952 @@ +--- +# Copyright (c) 1994, 2023, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JAVAC(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +javac - read Java declarations and compile them into class files + +## Synopsis + +`javac` \[*options*\] \[*sourcefiles-or-classnames*\] + +*options* +: Command-line options. + +*sourcefiles-or-classnames* +: Source files to be compiled (for example, `Shape.java`) or + the names of previously compiled classes to be processed for annotations + (for example, `geometry.MyShape`). + +## Description + +The `javac` command reads _source files_ that contain module, package and type +declarations written in the Java programming language, and compiles them into _class files_ +that run on the Java Virtual Machine. + +The `javac` command can also [process annotations](#annotation-processing) +in Java source files and classes. + +Source files must have a file name extension of `.java`. +Class files have a file name extension of `.class`. +Both source and class files normally have file names that identify the contents. +For example, a class called `Shape` would be declared in a source file +called `Shape.java`, and compiled into a class file called `Shape.class`. + +There are two ways to specify source files to `javac`: + +- For a small number of source files, you can list their file names on + the command line. + +- For a large number of source files, you can use the [`@`*filename*](#option-at) + option on the command line to specify an _argument file_ that lists + their file names. See [Standard Options] for a description of the + option and [Command-Line Argument Files] for a description of + `javac` argument files. + +The order of source files specified on the command line or in an +argument file is not important. `javac` will compile the files together, +as a group, and will automatically resolve any dependencies between +the declarations in the various source files. + +`javac` expects that source files are arranged in one or more directory +hierarchies on the file system, described in [Arrangement of Source +Code]. + +To compile a source file, `javac` needs to find the declaration of +every class or interface that is used, extended, or implemented by the +code in the source file. This lets `javac` check that the code has the +right to access those classes and interfaces. Rather than specifying +the source files of those classes and interfaces explicitly, you can +use command-line options to tell `javac` where to search for their +source files. If you have compiled those source files previously, you +can use options to tell `javac` where to search for the corresponding +class files. The options, which all have names ending in "path", are +described in [Standard Options], and further described in +[Configuring a Compilation] and [Searching for Module, Package and Type Declarations]. + +By default, `javac` compiles each source file to a class file in the +same directory as the source file. However, it is recommended to +specify a separate destination directory with the [`-d`](#option-d) option. + +Command-line [options] and [environment variables] also control how +`javac` performs various tasks: + +- Compiling code to run on earlier releases of the JDK. +- Compiling code to run under a debugger. +- Checking for stylistic issues in Java source code. +- Checking for problems in `javadoc` comments (`/** ... */`). +- Processing annotations in source files and class files. +- Upgrading and patching modules in the compile-time environment. + +`javac` supports [Compiling for Earlier Releases Of The Platform] +and can also be invoked from Java code using one of a number of [APIs] + +## Options + +`javac` provides [standard options], and [extra options] that are either +non-standard or are for advanced use. + +Some options take one or more arguments. +If an argument contains spaces or other whitespace characters, +the value should be quoted according to the conventions of the +environment being used to invoke javac. +If the option begins with a single dash (`-`) the argument should +either directly follow the option name, or should be separated with a +colon (`:`) or whitespace, depending on the option. If the option begins with +a double dash (`--`), the argument may be separated either by whitespace +or by an equals (`=`) character with no additional whitespace. +For example, + + -Aname="J. Duke" + -proc:only + -d myDirectory + --module-version 3 + --module-version=3 + +In the following lists of options, an argument of *path* represents +a search path, composed of a list of file system locations separated +by the platform path separator character, (semicolon `;` on Windows, +or colon `:` on other systems.) Depending on the option, the +file system locations may be directories, JAR files or JMOD files. + +### Standard Options + +`@`*filename* +: Reads options and file names from a file. To shorten or simplify the + `javac` command, you can specify one or more files that contain arguments + to the `javac` command (except [`-J`](#option-J) options). This lets you to create + `javac` commands of any length on any operating system. + See [Command-Line Argument Files]. + +`-A`*key*\[`=`*value*\] +: Specifies options to pass to annotation processors. These options are not + interpreted by `javac` directly, but are made available for use by + individual processors. The *key* value should be one or more identifiers + separated by a dot (`.`). + +`--add-modules` *module*`,`*module* +: Specifies root modules to resolve in addition to the initial modules, or + all modules on the module path if *module* is `ALL-MODULE-PATH`. + +`--boot-class-path` *path* or `-bootclasspath` *path* +: Overrides the location of the bootstrap class files. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or + [`-target`](#option-target) for details. For JDK 9 or later, see [`--system`](#option-system). + +`--class-path` *path*, `-classpath` *path*, or `-cp` *path* +: Specifies where to find user class files and annotation processors. This + class path overrides the user class path in the `CLASSPATH` environment + variable. + + - If `--class-path`, `-classpath`, or `-cp` are not specified, then the + user class path is the value of the `CLASSPATH` environment variable, + if that is set, or else the current directory. + + - If not compiling code for modules, if the [`--source-path`](#option-source-path) or -sourcepath` + option is not specified, then the user class path is also searched for source files. + + - If the [`-processorpath`](#option-processor-path) option is not specified, then the class path is + also searched for annotation processors. + +`-d` *directory* +: Sets the destination directory (or _class output directory_) for class files. + If a class is part of a package, then `javac` puts the class file in a + subdirectory that reflects the module name (if appropriate) and package name. + The directory, and any necessary subdirectories, will be created if they + do not already exist. + + If the `-d` option is not specified, then `javac` puts each class file in + the same directory as the source file from which it was generated. + + Except when compiling code for multiple modules, the contents of the + class output directory will be organized in a package hierarchy. + When compiling code for multiple modules, the contents of the output + directory will be organized in a module hierarchy, with the contents of each + module in a separate subdirectory, each organized as a package + hierarchy. + + **Note:** + When compiling code for one or more modules, the class output directory will + automatically be checked when searching for previously compiled classes. + When not compiling for modules, for backwards compatibility, + the directory is _not_ automatically checked for previously compiled classes, + and so it is recommended to specify the class output directory as one + of the locations on the user class path, using the `--class-path` option or one of + its alternate forms. + +`-deprecation` +: Shows a description of each use or override of a deprecated member or + class. Without the `-deprecation` option, `javac` shows a summary of the + source files that use or override deprecated members or classes. The + `-deprecation` option is shorthand for `-Xlint:deprecation`. + +`--enable-preview` +: Enables preview language features. Used in conjunction with either + [`-source`](#option-source) or [`--release`](#option-release). + +`-encoding` *encoding* +: Specifies character encoding used by source files, such as EUC-JP and + UTF-8. If the `-encoding` option is not specified, then the platform default + converter is used. + +`-endorseddirs` *directories* +: Overrides the location of the endorsed standards path. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or + [`-target`](#option-target) for details. + +`-extdirs` *directories* +: Overrides the location of the installed extensions. + `directories` is a list of directories, separated by the platform path separator + (`;` on Windows, and `:` otherwise). + Each JAR file in the specified directories is searched for class files. + All JAR files found become part of the class path. + + If you are compiling for a release of the platform that supports the + Extension Mechanism, then this option specifies the directories that + contain the extension classes. + See [Compiling for Other Releases of the Platform]. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or + [`-target`](#option-target) for details. + +`-g` +: Generates all debugging information, including local variables. By default, + only line number and source file information is generated. + +`-g:`\[`lines`, `vars`, `source`\] +: Generates only the kinds of debugging information specified by the + comma-separated list of keywords. Valid keywords are: + + `lines` + : Line number debugging information. + + `vars` + : Local variable debugging information. + + `source` + : Source file debugging information. + +`-g:none` +: Does not generate debugging information. + +`-h` *directory* +: Specifies where to place generated native header files. + + When you specify this option, a native header file is generated for each + class that contains native methods or that has one or more constants + annotated with the [`java.lang.annotation.Native`]( + ../../api/java.base/java/lang/annotation/Native.html) + annotation. If the class is part of a package, then the compiler puts the + native header file in a subdirectory that reflects the module name + (if appropriate) and package name. + The directory, and any necessary subdirectories, will be created if they + do not already exist. + +`--help`, `-help` or `-?` +: Prints a synopsis of the standard options. + +`--help-extra` or `-X` +: Prints a synopsis of the set of extra options. + +`--help-lint` +: Prints the supported keys for the `-Xlint` option. + +`-implicit:`\[`none`, `class`\] +: Specifies whether or not to generate class files for implicitly referenced + files: + + - `-implicit:class` --- Automatically generates class files. + + - `-implicit:none` --- Suppresses class file generation. + + If this option is not specified, then the default automatically generates + class files. In this case, the compiler issues a warning if any class files + are generated when also doing annotation processing. The warning is not + issued when the `-implicit` option is explicitly set. + See [Searching for Module, Package and Type Declarations]. + +`-J`*option* +: Passes *option* to the runtime system, where *option* is one of the Java + options described on [java](java.html) command. For example, `-J-Xms48m` + sets the startup memory to 48 MB. + + **Note:** The `CLASSPATH` environment variable, `-classpath` option, `-bootclasspath` + option, and `-extdirs` option do not specify the classes used to run + `javac`. Trying to customize the compiler implementation with these options + and variables is risky and often does not accomplish what you want. If you + must customize the compiler implementation, then use the `-J` option to + pass options through to the underlying Java launcher. + +`--limit-modules` *module*`,`*module*\* +: Limits the universe of observable modules. + +`--module` *module-name* (`,`*module-name*)* or `-m` *module-name* (`,`*module-name*)* +: Compiles those source files in the named modules that are newer + than the corresponding files in the output directory. + +`--module-path` *path* or `-p` *path* +: Specifies where to find application modules. + +`--module-source-path` *module-source-path* +: Specifies where to find source files when compiling code + in multiple modules. See [The Module Source Path Option]. + +`--module-version` *version* +: Specifies the version of modules that are being compiled. + +`-nowarn` +: Disables warning messages. This option operates the same as the + `-Xlint:none` option. + +`-parameters` +: Generates metadata for reflection on method parameters. Stores formal + parameter names of constructors and methods in the generated class file so + that the method `java.lang.reflect.Executable.getParameters` from the + Reflection API can retrieve them. + +`-proc:`\[`none`, `only`, `full`\] +: Controls whether annotation processing and compilation are done. + `-proc:none` means that compilation takes place without annotation + processing. `-proc:only` means that only annotation processing is done, + without any subsequent compilation. If this option is not used, or + `-proc:full` is specified, annotation processing and compilation are done. + +`-processor` *class1*\[`,`*class2*`,`*class3*...\] +: Names of the annotation processors to run. This bypasses the default + discovery process. + +`--processor-module-path` *path* +: Specifies the module path used for finding annotation processors. + +`--processor-path` *path* or `-processorpath` *path* +: Specifies where to find annotation processors. If this option is not used, + then the class path is searched for processors. + +`-profile` *profile* +: Checks that the API used is available in the specified profile. + This option is deprecated and may be removed in a future release. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`--release` *release* +: Compiles source code according to the rules of the Java programming language + for the specified Java SE release, generating class files which target + that release. + Source code is compiled against the combined Java SE and JDK API for the + specified release. + + The supported values of *release* are the current Java SE release and a + limited number of previous releases, detailed in the command-line help. + + For the current release, the Java SE API consists of the `java.*`, + `javax.*`, and `org.*` packages that are exported by the Java SE modules in + the release; the JDK API consists of the `com.*` and `jdk.*` packages that + are exported by the JDK modules in the release, plus the `javax.*` packages + that are exported by standard, but non-Java SE, modules in the release. + + For previous releases, the Java SE API and the JDK API are as defined in + that release. + + **Note:** When using `--release`, you cannot also use the [`--source`](#option-source)/`-source` or + [`--target`](#option-target)/`-target` options. + + **Note:** When using `--release` to specify a release that supports the Java + Platform Module System, the `--add-exports` option cannot be used to + enlarge the set of packages exported by the Java SE, JDK, and standard + modules in the specified release. + +`-s` *directory* +: Specifies the directory used to place the generated source files. If a + class is part of a package, then the compiler puts the source file in a + subdirectory that reflects the module name (if appropriate) and package name. + The directory, and any necessary subdirectories, will be created if they + do not already exist. + + Except when compiling code for multiple modules, the contents of the + source output directory will be organized in a package hierarchy. + When compiling code for multiple modules, the contents of the source output directory will be + organized in a module hierarchy, with the contents of each + module in a separate subdirectory, each organized as a package + hierarchy. + +`--source` *release* or `-source` *release* +: Compiles source code according to the rules of the Java programming language + for the specified Java SE release. + The supported values of *release* are the current Java SE release and a + limited number of previous releases, detailed in the command-line help. + + If the option is not specified, the default is to compile source code + according to the rules of the Java programming language for the current + Java SE release. + +`--source-path` *path* or `-sourcepath` *path* +: Specifies where to find source files. + Except when compiling multiple modules together, this is the source code path + used to search for class or interface definitions. + + **Note:** Classes found through the class path might be recompiled when their source + files are also found. See [Searching for Module, Package and Type Declarations]. + +`--system` *jdk* \| `none` +: Overrides the location of system modules. + +`--target` *release* or `-target` *release* +: Generates `class` files suitable for the specified Java SE release. + The supported values of *release* are the current Java SE release and a + limited number of previous releases, detailed in the command-line help. + + **Note:** The target release must be equal to or higher than the source release. + (See [`--source`](#option-source).) + +`--upgrade-module-path` *path* +: Overrides the location of upgradeable modules. + +`-verbose` +: Outputs messages about what the compiler is doing. Messages include + information about each class loaded and each source file compiled. + +`--version` or `-version` +: Prints version information. + +`-Werror` +: Terminates compilation when warnings occur. + +### Extra Options + +`--add-exports` *module*`/`*package*`=`*other-module*(`,`*other-module*)\* +: Specifies a package to be considered as exported from its defining module + to additional modules or to all unnamed modules when the value of + *other-module* is `ALL-UNNAMED`. + +`--add-reads` *module*`=`*other-module*(`,`*other-module*)\* +: Specifies additional modules to be considered as required by a given + module. + +`--default-module-for-created-files` *module-name* +: Specifies the fallback target module for files created by annotation + processors, if none is specified or inferred. + +`--disable-line-doc-comments` +: Disables support for documentation comments with lines beginning ///. + +`-Djava.endorsed.dirs=`*dirs* +: Overrides the location of the endorsed standards path. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`-Djava.ext.dirs=`*dirs* +: Overrides the location of installed extensions. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`--patch-module` *module*`=`*path* +: Overrides or augments a module with classes and resources in JAR files or + directories. + +`-Xbootclasspath:`*path* +: Overrides the location of the bootstrap class files. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`-Xbootclasspath/a:`*path* +: Adds a suffix to the bootstrap class path. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`-Xbootclasspath/p:`*path* +: Adds a prefix to the bootstrap class path. + + **Note:** This can only be used when compiling for releases prior to JDK 9. + As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), + or [`-target`](#option-target) for details. + +`-Xdiags:`\[`compact`, `verbose`\] +: Selects a diagnostic mode. + +`-Xdoclint` +: Enables recommended checks for problems in documentation comments. + +`-Xdoclint:`(`all`|`none`|\[`-`\]*group*)\[`/`*access*\] +: Enables or disables specific groups of checks in documentation comments. + + *group* can have one of the following values: + `accessibility`, `html`, `missing`, `reference`, `syntax`. + + The variable *access* specifies the minimum visibility level of classes and + members that the `-Xdoclint` option checks. It can have one of the + following values (in order of most to least visible): + `public`, `protected`, `package`, `private`. + + The default *access* level is `private`. + + When prefixed by `doclint:`, the *group* names and `all` can be used with `@SuppressWarnings` + to suppress warnings about documentation comments in parts of the code being compiled. + + For more information about these groups of checks, see the [DocLint](javadoc.html#doclint) + section of the `javadoc` command documentation. + The `-Xdoclint` option is disabled by default in the `javac` command. + + For example, the following option checks classes and members (with all + groups of checks) that have the access level of protected and higher (which + includes protected and public): + + > `-Xdoclint:all/protected` + + The following option enables all groups of checks for all access levels, + except it will not check for HTML errors for classes and members that have the + access level of package and higher (which includes package, protected and + public): + + > `-Xdoclint:all,-html/package` + +`-Xdoclint/package:`\[`-`\]*packages*(`,`\[`-`\]*package*)\* +: Enables or disables checks in specific packages. Each *package* is either + the qualified name of a package or a package name prefix followed by `.*`, + which expands to all sub-packages of the given package. Each *package* can + be prefixed with a hyphen (`-`) to disable checks for a specified package + or packages. + + For more information, see the [DocLint](javadoc.html#doclint) + section of the `javadoc` command documentation. + +`-Xlint` +: Enables all recommended warnings. In this release, enabling all available + warnings is recommended. + +`-Xlint:`\[`-`\]*key*(`,`\[`-`\]*key*)\* +: Supplies warnings to enable or disable, separated by comma. Precede a key + by a hyphen (`-`) to disable the specified warning. + + Supported values for *key* are: + + - `all`: Enables all warnings. + + - `auxiliaryclass`: Warns about an auxiliary class that is hidden in a + source file, and is used from other files. + + - `cast`: Warns about the use of unnecessary casts. + + - `classfile`: Warns about the issues related to classfile contents. + + - `dangling-doc-comments`: Warns about extra or misplaced documentation + comments near the beginning of a declaration. + + - `deprecation`: Warns about the use of deprecated items. + + - `dep-ann`: Warns about the items marked as deprecated in `javadoc` but + without the `@Deprecated` annotation. + + - `divzero`: Warns about the division by the constant integer 0. + + - `empty`: Warns about an empty statement after `if`. + + - `exports`: Warns about the issues regarding module exports. + + - `fallthrough`: Warns about the falling through from one case of a + switch statement to the next. + + - `finally`: Warns about `finally` clauses that do not terminate normally. + + - `incubating`: Warns about the use of incubating modules. + + - `lossy-conversions`: Warns about possible lossy conversions + in compound assignment. + + - `missing-explicit-ctor`: Warns about missing explicit constructors in + public and protected classes in exported packages. + + - `module`: Warns about the module system-related issues. + + - `opens`: Warns about the issues related to module opens. + + - `options`: Warns about the issues relating to use of command line + options. + + - `output-file-clash`: Warns if any output file is overwritten during compilation. + This can occur, for example, on case-insensitive filesystems. + + - `overloads`: Warns about the issues related to method overloads. + + - `overrides`: Warns about the issues related to method overrides. + + - `path`: Warns about the invalid path elements on the command line. + + - `preview`: Warns about the use of preview language features. + + - `processing`: Warns about the issues related to annotation processing. + + - `rawtypes`: Warns about the use of raw types. + + - `removal`: Warns about the use of an API that has been marked for + removal. + + - `restricted`: Warns about the use of restricted methods. + + - `requires-automatic`: Warns developers about the use of automatic + modules in requires clauses. + + - `requires-transitive-automatic`: Warns about automatic modules in + requires transitive. + + - `serial`: Warns about the serializable classes that do not provide a + serial version ID. Also warns about access to non-public members from a + serializable element. + + - `static`: Warns about the accessing a static member using an instance. + + - `strictfp`: Warns about unnecessary use of the `strictfp` modifier. + + - `synchronization`: Warns about synchronization attempts on instances + of value-based classes. + + - `text-blocks`: Warns about inconsistent white space characters in text + block indentation. + + - `this-escape`: Warns about constructors leaking `this` prior to subclass initialization. + + - `try`: Warns about the issues relating to the use of try blocks (that + is, try-with-resources). + + - `unchecked`: Warns about the unchecked operations. + + - `varargs`: Warns about the potentially unsafe `vararg` methods. + + - `none`: Disables all warnings. + + With the exception of `all` and `none`, the keys can be used with + the `@SuppressWarnings` annotation to suppress warnings in a part + of the source code being compiled. + + See [Examples of Using -Xlint keys]. + +`-Xmaxerrs` *number* +: Sets the maximum number of errors to print. + +`-Xmaxwarns` *number* +: Sets the maximum number of warnings to print. + +`-Xpkginfo:`\[`always`, `legacy`, `nonempty`\] +: Specifies when and how the `javac` command generates `package-info.class` + files from `package-info.java` files using one of the following options: + + `always` + : Generates a `package-info.class` file for every `package-info.java` + file. This option may be useful if you use a build system such as Ant, + which checks that each `.java` file has a corresponding `.class` file. + + `legacy` + : Generates a `package-info.class` file only if `package-info.java` + contains annotations. This option does not generate a + `package-info.class` file if `package-info.java` contains only + comments. + + **Note:** A `package-info.class` file might be generated but be empty if all the + annotations in the `package-info.java` file have + `RetentionPolicy.SOURCE`. + + `nonempty` + : Generates a `package-info.class` file only if `package-info.java` + contains annotations with `RetentionPolicy.CLASS` or + `RetentionPolicy.RUNTIME`. + +`-Xplugin:`*name* *args* +: Specifies the name and optional arguments for a plug-in to be run. + If *args* are provided, *name* and *args* should be quoted or otherwise + escape the whitespace characters between the name and all the arguments. + For details on the API for a plugin, see the API documentation for + [jdk.compiler/com.sun.source.util.Plugin](../../api/jdk.compiler/com/sun/source/util/Plugin.html). + +`-Xprefer:`\[`source`, `newer`\] +: Specifies which file to read when both a source file and class file are + found for an implicitly compiled class using one of the following options. + See [Searching for Module, Package and Type Declarations]. + + - `-Xprefer:newer`: Reads the newer of the source or class files for a + type (default). + + - `-Xprefer:source` : Reads the source file. Use `-Xprefer:source` when + you want to be sure that any annotation processors can access + annotations declared with a retention policy of `SOURCE`. + +`-Xprint` +: Prints a textual representation of specified types for debugging purposes. + This does not perform annotation processing or compilation. The format of + the output could change. + +`-XprintProcessorInfo` +: Prints information about which annotations a processor is asked to process. + +`-XprintRounds` +: Prints information about initial and subsequent annotation processing + rounds. + +`-Xstdout` *filename* +: Sends compiler messages to the named file. By default, compiler messages go + to `System.err`. + +## Environment Variables + +### CLASSPATH + +If the [`--class-path`](#option-class-path) option or any of its alternate forms are not specified, +the class path will default to the value of the `CLASSPATH` environment +variable if it is set. +However, it is recommended that this environment variable should _not_ be set, +and that the `--class-path` option should be used to provide an explicit +value for the class path when one is required. + +### JDK\_JAVAC\_OPTIONS + +The content of the `JDK_JAVAC_OPTIONS` environment variable, separated by +white-spaces ( ) or white-space characters (`\n`, `\t`, `\r`, or `\f`) is +prepended to the command line arguments passed to `javac` as a list of +arguments. + +The encoding requirement for the environment variable is the same as the +`javac` command line on the system. `JDK_JAVAC_OPTIONS` environment variable +content is treated in the same manner as that specified in the command line. + +Single quotes (`'`) or double quotes (`"`) can be used to enclose arguments +that contain whitespace characters. All content between the open quote and the +first matching close quote are preserved by simply removing the pair of quotes. +In case a matching quote is not found, the launcher will abort with an error +message. `@`*files* are supported as they are specified in the command line. +However, as in `@`*files*, use of a wildcard is not supported. + +**Examples of quoting arguments containing white spaces:** + +> `export JDK_JAVAC_OPTIONS='@"C:\white spaces\argfile"'` + +> `export JDK_JAVAC_OPTIONS='"@C:\white spaces\argfile"'` + +> `export JDK_JAVAC_OPTIONS='@C:\"white spaces"\argfile'` + +## Command-Line Argument Files + +An argument file can include command-line options and source file names in any +combination. The arguments within a file can be separated by spaces or new line +characters. If a file name contains embedded spaces, then put the whole file +name in double quotation marks. + +File names within an argument file are relative to the current directory, not +to the location of the argument file. Wildcards (`*`) are not allowed in these +lists (such as for specifying `*.java`). Use of the at sign (`@`) to +recursively interpret files is not supported. The `-J` options are not supported +because they're passed to the launcher, which does not support argument files. + +When executing the `javac` command, pass in the path and name of each argument +file with the at sign (`@`) leading character. When the `javac` command +encounters an argument beginning with the at sign (`@`), it expands the +contents of that file into the argument list. + + +### Examples of Using javac @filename + +Single Argument File +: You could use a single argument file named `argfile` to hold all `javac` + arguments: + + > `javac @argfile` + + This argument file could contain the contents of both files shown in the + following **Two Argument Files** example. + +Two Argument Files +: You can create two argument files: one for the `javac` options and the + other for the source file names. Note that the following lists have no + line-continuation characters. + + Create a file named `options` that contains the following: + + **Linux and macOS:** + + ``` + -d classes + -g + -sourcepath /java/pubs/ws/1.3/src/share/classes + ``` + + **Windows:** + + ``` + -d classes + -g + -sourcepath C:\java\pubs\ws\1.3\src\share\classes + ``` + + Create a file named `sources` that contains the following: + + ``` + MyClass1.java + MyClass2.java + MyClass3.java + ``` + + Then, run the `javac` command as follows: + + > `javac @options @sources` + +Argument Files with Paths +: The argument files can have paths, but any file names inside the files are + relative to the current working directory (not `path1` or `path2`): + + > `javac @path1/options @path2/sources` + +## Arrangement of Source Code + +In the Java language, classes and interfaces can be organized into +packages, and packages can be organized into modules. `javac` expects +that the physical arrangement of source files in directories of the +file system will mirror the organization of classes into packages, and +packages into modules. + +It is a widely adopted convention that module names and package names +begin with a lower-case letter, and that class names begin with an +upper-case letter. + +### Arrangement of Source Code for a Package + +When classes and interfaces are organized into a package, the package +is represented as a directory, and any subpackages are represented as +subdirectories. + +For example: + +- The package `p` is represented as a directory called `p`. + +- The package `p.q` -- that is, the subpackage `q` of package `p` -- + is represented as the subdirectory `q` of directory `p`. The + directory tree representing package `p.q` is therefore `p\q` + on Windows, and `p/q` on other systems. + +- The package `p.q.r` is represented as the directory tree `p\q\r` + (on Windows) or `p/q/r` (on other systems). + +Within a directory or subdirectory, `.java` files represent classes +and interfaces in the corresponding package or subpackage. + +For example: + +- The class `X` declared in package `p` is represented by the file + `X.java` in the `p` directory. + +- The class `Y` declared in package `p.q` is represented by the file + `Y.java` in the `q` subdirectory of directory `p`. + +- The class `Z` declared in package `p.q.r` is represented by the file + `Z.java` in the `r` subdirectory of `p\q` (on Windows) or `p/q` + (on other systems). + +In some situations, it is convenient to split the code into +separate directories, each structured as described above, and +the aggregate list of directories specified to `javac`. + +### Arrangement of Source Code for a Module + +In the Java language, a module is a set of packages designed for +reuse. In addition to `.java` files for classes and interfaces, each +module has a source file called `module-info.java` which: + +1. declares the module's name; + +2. lists the packages exported by the module (to allow reuse by other + modules); + +3. lists other modules required by the module (to reuse their exported + packages). + +When packages are organized into a module, the module is represented +by one or more directories representing the packages in the module, +one of which contains the `module-info.java` file. It may be convenient, +but it is not required, to use a single directory, named after the module, +to contain the `module-info.java` file alongside the directory tree which +represents the packages in the module (i.e., the _package hierarchy_ +described above). The exact arrangement of source code for a module +is typically dictated by the conventions adopted by a development +environment (IDE) or build system. + +For example: + +- The module `a.b.c` may be represented by the directory `a.b.c`, on all + systems. + +- The module's declaration is represented by the file + `module-info.java` in the `a.b.c` directory. + +- If the module contains package `p.q.r`, then the `a.b.c` directory + contains the directory tree `p\q\r` (on Windows) or `p/q/r` + (on other systems). + +The development environment may prescribe some directory hierarchy +between the directory named for the module and the source files to +be read by `javac`. + +For example: + +- The module `a.b.c` may be represented by the directory `a.b.c` + +- The module's declaration and the module's packages may be in + some subdirectory of `a.b.c`, such as `src\main\java` (on Windows) + or `src/main/java` (on other systems). + + +## Configuring a Compilation + +This section describes how to configure `javac` to perform a basic compilation. + +See [Configuring the Module System] for additional details for use when compiling +for a release of the platform that supports modules. + +### Source Files + +* Specify the source files to be compiled on the command line. + +If there are no compilation errors, the corresponding class files will +be placed in the [output directory]. + +Some systems may limit the amount you can put on a command line; +to work around those limits, you can use [argument files](#command-line-argument-files). + +When compiling code for modules, you can also specify source files indirectly, +by using the [`--module`](#option-module) or `-m` option. + +### Output Directory + +* Use the [`-d`](#option-d) option to specify an output directory in which to put the compiled class files. + +This will normally be organized in a [package hierarchy](#package-hierarchy), +unless you are compiling source code from multiple modules, in which case it will be +organized as a [module hierarchy](#module-hierarchy). + +When the compilation has been completed, if you are compiling one or more modules, +you can place the output directory on the module path for the Java [launcher](java.html); +otherwise, you can place the place the output directory on the class path +for the Java launcher. + +### Precompiled Code + +The code to be compiled may refer to libraries beyond what is provided by the platform. +If so, you must place these libraries on the class path or module path. +If the library code is not in a module, place it on the class path; +if it is in a module, place it on the module path. + +* Use the [`--class-path`](#option-class-path) option to specify libraries to be placed on the class path. + Locations on the class path should be organized in a [package hierarchy](#package-hierarchy). + You can also use alternate forms of the option: `-classpath` or `-cp`. + +* Use the [`--module-path`](#option-module-path) option to specify libraries to be placed on the module path. + Locations on the module path should either be modules or directories of modules. + You can also use an alternate form of the option: `-p`. + + See [Configuring the Module System] for details on how to modify the default + configuration of library modules. + +**Note**: the options for the class path and module path are not mutually +exclusive, although it is not common to specify the class path when compiling +code for one or more modules. + +### Additional Source Files + +The code to be compiled may refer to types in additional source files that are not +specified on the command line. +If so, you must put those source files on either the source path or module path. +You can only specify one of these options: if you are not compiling code for a module, +or if you are only compiling code for a single module, use the source path; +if you are compiling code for multiple modules, use the module source path. + +* Use the [`--source-path`](#option-source-path) option to specify the locations of additional source + files that may be read by javac. + Locations on the source path should be organized in a [package hierarchy](#package-hierarchy). + You can also use an alternate form of the option: `-sourcepath`. + +* Use the [`--module-source-path`](#option-module-source-path) option one or more times to specify the location + of additional source files in different modules that may be read by javac, + or when compiling source files in multiple modules. + You can either specify the locations for each module [individually](#module-specific-form), + or you can organize the source files so that you can specify the locations all + [together](#module-pattern-form). For more details, see [The Module Source Path Option]. + +If you want to be able to refer to types in additional source files but do not +want them to be compiled, use the [`-implicit`](#option-implicit) option. + +**Note**: if you are compiling code for multiple modules, you must always specify +a module source path, and all source files specified on the command line must be +in one of the directories on the module source path, or in a subdirectory thereof. + + +### Example of Compiling Multiple Source Files + +This example compiles the `Aloha.java`, `GutenTag.java`, `Hello.java`, and +`Hi.java` source files in the `greetings` package. + +**Linux and macOS:** + +``` +% javac greetings/*.java +% ls greetings +Aloha.class GutenTag.class Hello.class Hi.class +Aloha.java GutenTag.java Hello.java Hi.java +``` + +**Windows:** + +``` +C:\>javac greetings\*.java +C:\>dir greetings +Aloha.class GutenTag.class Hello.class Hi.class +Aloha.java GutenTag.java Hello.java Hi.java +``` + +### Example of Specifying a User Class Path + +After changing one of the source files in the previous example, recompile it: + +**Linux and macOS:** + +``` +pwd +/examples +javac greetings/Hi.java +``` + +**Windows:** + +``` +C:\>cd +\examples +C:\>javac greetings\Hi.java +``` + +Because `greetings.Hi` refers to other classes in the `greetings` package, the +compiler needs to find these other classes. The previous example works because +the default user class path is the directory that contains the package +directory. If you want to recompile this file without concern for which +directory you are in, then add the examples directory to the user class path by +setting `CLASSPATH`. This example uses the `-classpath` option. + +**Linux and macOS:** + +> `javac -classpath /examples /examples/greetings/Hi.java` + +**Windows:** + +> `C:\>javac -classpath \examples \examples\greetings\Hi.java` + +If you change `greetings.Hi` to use a banner utility, then that utility also +needs to be accessible through the user class path. + +**Linux and macOS:** + +``` +javac -classpath /examples:/lib/Banners.jar \ + /examples/greetings/Hi.java +``` + +**Windows:** + +``` +C:\>javac -classpath \examples;\lib\Banners.jar ^ + \examples\greetings\Hi.java +``` + +To execute a class in the `greetings` package, the program needs access to the +`greetings` package, and to the classes that the `greetings` classes use. + +**Linux and macOS:** + +> `java -classpath /examples:/lib/Banners.jar greetings.Hi` + +**Windows:** + +> `C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi` + +## Configuring the Module System + +If you want to include additional modules in your compilation, use the +[`--add-modules`](#option-add-modules) option. +This may be necessary when you are compiling code that is not in a module, +or which is in an automatic module, and the code refers to API in the additional +modules. + +If you want to restrict the set of modules in your compilation, use the +[`--limit-modules`](#option-limit-modules) option. +This may be useful if you want to ensure that the code you are compiling +is capable of running on a system with a limited set of modules installed. + +If you want to break encapsulation and specify that additional packages +should be considered as exported from a module, use the [`--add-exports`](#option-add-exports) option. +This may be useful when performing white-box testing; relying on access +to internal API in production code is strongly discouraged. + +If you want to specify that additional packages +should be considered as required by a module, use the [`--add-reads`](#option-add-reads) option. +This may be useful when performing white-box testing; relying on access +to internal API in production code is strongly discouraged. + +You can patch additional content into any module using the +[`--patch-module`](#option-patch-module) option. See [Patching a Module] for more details. + +## Searching for Module, Package and Type Declarations + +To compile a source file, the compiler often needs information about a module +or type, but the declaration is not in the source files specified on the command +line. + +`javac` needs type information for every class or interface used, +extended, or implemented in the source file. This includes classes and +interfaces not explicitly mentioned in the source file, but that provide +information through inheritance. + +For example, when you create a subclass of `java.awt.Window`, you are also +using the ancestor classes of `Window`: `java.awt.Container`, +`java.awt.Component`, and `java.lang.Object`. + +When compiling code for a module, the compiler also needs to have available +the declaration of that module. + +A successful search may produce a class file, a source file, or both. If +both are found, then you can use the [`-Xprefer`](#option-Xprefer) option to instruct the compiler +which to use. + +If a search finds and uses a source file, then by default `javac` +compiles that source file. This behavior can be altered with +[`-implicit`](#option-implicit). + +The compiler might not discover the need for some type information until after +annotation processing completes. When the type information is found in a source +file and no [`-implicit`](#option-implicit) option is specified, the compiler gives a warning that +the file is being compiled without being subject to annotation processing. To +disable the warning, either specify the file on the command line (so that it +will be subject to annotation processing) or use the [`-implicit`](#option-implicit) option to +specify whether or not class files should be generated for such source files. + +The way that `javac` locates the declarations of those types +depends on whether the reference exists within code for a module or not. + +### Searching Package Oriented Paths + +When searching for a source or class file on a path composed of package oriented +locations, `javac` will check each location on the path in turn for the +possible presence of the file. The first occurrence of a particular file +shadows (hides) any subsequent occurrences of like-named files. This shadowing +does not affect any search for any files with a different name. This can be +convenient when searching for source files, which may be grouped in different +locations, such as shared code, platform-specific code and generated code. +It can also be useful when injecting alternate versions of a class file into +a package, to debugging or other instrumentation reasons. But, it can also +be dangerous, such as when putting incompatible different versions of a library +on the class path. + +### Searching Module Oriented Paths + +Prior to scanning any module paths for any package or type declarations, +`javac` will lazily scan the following paths and locations to determine +the modules that will be used in the compilation. + +* The module source path (see the [`--module-source-path`](#option-module-source-path) option) +* The path for upgradeable modules (see the [`--upgrade-module-path`](#option-upgrade-module-path) option) +* The system modules (see the [`--system`](#option-system) option) +* The user module path ( see the [`--module-path`](#option-module-path) option) + +For any module, the first occurrence of the module during the scan completely +shadows (hides) any subsequent appearance of a like-named module. While locating +the modules, `javac` is able to determine the packages exported by the module +and to associate with each module a package oriented path for the contents of +the module. For any previously compiled module, this path will typically be a +single entry for either a directory or a file that provides an internal +directory-like hierarchy, such as a JAR file. Thus, when searching for a type +that is in a package that is known to be exported by a module, `javac` can +locate the declaration directly and efficiently. + +### Searching for the Declaration of a Module + +If the module has been previously compiled, the module declaration is +located in a file named `module-info.class` in the root of the package hierarchy +for the content of the module. + +If the module is one of those currently being compiled, the module declaration +will be either the file named `module-info.class` in the root of the +package hierarchy for the module in the class output directory, or the +file named `module-info.java` in one of the locations on the source path +or one the module source path for the module. + +### Searching for the Declaration of a Type When the Reference is not in a Module + +When searching for a type that is referenced in code that is not in a module, +`javac` will look in the following places: + +* The platform classes (or the types in exported packages of the platform modules) + (This is for compiled class files only.) + +* Types in exported packages of any modules on the module path, if applicable. + (This is for compiled class files only.) + +* Types in packages on the class path and/or source path: + + * If both are specified, `javac` looks for compiled class files on the class path + and for source files on the source path. + + * If the class path is specified, but not source path, `javac` looks for both + compiled class files and source files on the class path. + + * If the class path is not specified, it defaults to the current directory. + +When looking for a type on the class path and/or source path, if both a compiled +class file and a source file are found, the most recently modified file will +be used by default. +If the source file is newer, it will be compiled and will may override any +previously compiled version of the file. You can use the [`-Xprefer`](#option-Xprefer) option +to override the default behavior. + +### Searching for the Declaration of a Type When the Reference is in a Module + +When searching for a type that is referenced in code in a module, +`javac` will examine the declaration of the enclosing module to determine +if the type is in a package that is exported from another module that is +readable by the enclosing module. +If so, `javac` will simply and directly go to the definition of that module +to find the definition of the required type. +Unless the module is another of the modules being compiled, `javac` will +only look for compiled class files files. In other words, `javac` will +not look for source files in platform modules or modules on the module path. + +If the type being referenced is not in some other readable module, +`javac` will examine the module being compiled to try and find the +declaration of the type. +`javac` will look for the declaration of the type as follows: + +* Source files specified on the command line or on the source path or + module source path. + +* Previously compiled files in the output directory. + + +## Directory Hierarchies + +`javac` generally assumes that source files and compiled class files will be +organized in a file system directory hierarchy or in a type of file that +supports in an internal directory hierarchy, such as a JAR file. +Three different kinds of hierarchy are supported: a _package hierarchy_, +a _module hierarchy_, and a _module source hierarchy_. + +While `javac` is fairly relaxed about the organization of source code, +beyond the expectation that source will be organized in one or package +hierarchies, and can generally accommodate organizations prescribed by +development environments and build tools, Java tools in general, +and `javac` and the Java launcher in particular, are more stringent +regarding the organization of compiled class files, and will be +organized in package hierarchies or module hierarchies, as appropriate. + +The location of these hierarchies are specified to `javac` with command-line +options, whose names typically end in "path", like [`--source-path`](#option-source-path) or +[`--class-path`](#option-class-path). Also as a general rule, path options whose name includes the +word `module`, like [`--module-path`](#option-module-path), are used to specify module hierarchies, +although some module-related path options allow a package hierarchy to be +specified on a per-module basis. All other path options are used to specify +package hierarchies. + +### Package Hierarchy + +In a package hierarchy, directories and subdirectories are used +to represent the component parts of the package name, with the source +file or compiled class file for a type being stored as a file with an +extension of `.java` or `.class` in the most nested directory. + +For example, in a package hierarchy, the source file for a class +`com.example.MyClass` will be stored in the file _com/example/MyClass.java_ + +### Module Hierarchy + +In a module hierarchy, the first level of directories are named +for the modules in the hierarchy; within each of those directories +the contents of the module are organized in package hierarchies. + +For example, in a module hierarchy, the compiled class file for a type called +`com.example.MyClass` in a module called `my.library` will be stored in +_my.library/com/example/MyClass.class_. + +The various output directories used by `javac` (the class output directory, +the source output directory, and native header output directory) +will all be organized in a module hierarchy when multiple modules are being compiled. + +### Module Source Hierarchy + +Although the source for each individual module should always be +organized in a package hierarchy, it may be convenient to group +those hierarchies into a module source hierarchy. This is similar +to a module hierarchy, except that there may be intervening directories +between the directory for the module and the directory that is +the root of the package hierarchy for the source code of the module. + +For example, in a module source hierarchy, the source file for a type called +`com.example.MyClass` in a module called `my.library` may be stored in a +file such as +_my.library/src/main/java/com/example/MyClass.java_. + +## The Module Source Path Option + +The [`--module-source-path`](#option-module-source-path) option has two forms: a _module-specific form_, +in which a package path is given for each module containing code to be compiled, +and a _module-pattern_ form, in which the source path for each module is specified +by a pattern. +The module-specific form is generally simpler to use when only a small number of +modules are involved; the module-pattern form may be more convenient when the +number of modules is large and the modules are organized in a regular manner that +can be described by a pattern. + +Multiple instances of the `--module-source-path` option may be given, each one +using either the module-pattern form or the module-specific form, subject to the +following limitations: + +* the module-pattern form may be used at most once +* the module-specific form may be used at most once for any given module + +If the module-specific form is used for any module, the associated search path +overrides any path that might otherwise have been inferred from the module-pattern form. + +### Module-specific form + +The module-specific form allows an explicit search path to be given for any specific module. +This form is: + +* `--module-source-path` *module-name*`=`*file-path* (*path-separator* *file-path*)* + +The path separator character is `;` on Windows, and `:` otherwise. + +**Note:** this is similar to the form used for the [`--patch-module`](#option-patch-module) option. + +### Module-pattern form + +The module-pattern form allows a concise specification of the module source path +for any number of modules organized in regular manner. + +* `--module-source-path` *pattern* + +The pattern is defined by the following rules, which are applied in order: + +* The argument is considered to be a series of segments separated by the path + separator character (`;` on Windows, and `:` otherwise). + +* Each segment containing curly braces of the form + + string1{alt1 ( ,alt2 )* } string2 + + is considered to be replaced by a series of segments formed by "expanding" the braces: + + string1 alt1 string2 + string1 alt2 string2 + and so on... + + The braces may be nested. + + This rule is applied for all such usages of braces. + + * Each segment must have at most one asterisk (`*`). + If a segment does not contain an asterisk, it is considered to be as though the + file separator character and an asterisk are appended. + + For any module _M_, the source path for that module is formed from the series + of segments obtained by substituting the module name _M_ for the asterisk in + each segment. + + **Note**: in this context, the asterisk is just used as a special marker, to + denote the position in the path of the module name. It should not be confused + with the use of `*` as a file name wildcard character, as found on most + operating systems. + +## Patching Modules + +javac allows any content, whether in source or compiled form, to be patched +into any module using the [`--patch-module`](#option-patch-module) option. +You may want to do this to compile alternative implementations of a class +to be patched at runtime into a JVM, or to inject additional classes into +the module, such as when testing. + +The form of the option is: + +* `--patch-module` *module-name*`=`*file-path* (*path-separator* *file-path* )* + +The path separator character is `;` on Windows, and `:` otherwise. +The paths given for the module must specify the root of a +package hierarchy for the contents of the module + +The option may be given at most once for any given module. +Any content on the path will hide any like-named content later in the path +and in the patched module. + +When patching source code into more than one module, the [`--module-source-path`](#option-module-source-path) +must also be used, so that the output directory is organized in a module hierarchy, +and capable of holding the compiled class files for the modules being compiled. + +## Annotation Processing + +The `javac` command provides direct support for annotation processing. + +The API for annotation processors is defined in the +`javax.annotation.processing` and `javax.lang.model` packages and subpackages. + +### How Annotation Processing Works + +Unless annotation processing is disabled with the [`-proc:none`](#option-proc) option, the +compiler searches for any annotation processors that are available. The search +path can be specified with the [`-processorpath`](#option-processor-path) option. If no path is +specified, then the user class path is used. Processors are located by means of +service provider-configuration files named +`META-INF/services/javax.annotation.processing.Processor` on the search path. +Such files should contain the names of any annotation processors to be used, +listed one per line. Alternatively, processors can be specified explicitly, +using the [`-processor`](#option-processor) option. + +After scanning the source files and classes on the command line to determine +what annotations are present, the compiler queries the processors to determine +what annotations they process. When a match is found, the processor is called. +A processor can claim the annotations it processes, in which case no further +attempt is made to find any processors for those annotations. After all of the +annotations are claimed, the compiler does not search for additional +processors. + +If any processors generate new source files, then another round of annotation +processing occurs: Any newly generated source files are scanned, and the +annotations processed as before. Any processors called on previous rounds are +also called on all subsequent rounds. This continues until no new source files +are generated. + +After a round occurs where no new source files are generated, the annotation +processors are called one last time, to give them a chance to complete any +remaining work. Finally, unless the [`-proc:only`](#option-proc) option is used, the compiler +compiles the original and all generated source files. + +If you use an annotation processor that generates additional source +files to be included in the compilation, you can specify a default +module to be used for the newly generated files, for use when a +module declaration is not also generated. In this case, use the +[`--default-module-for-created-files`](#option-default-module-for-created-files) option. + +### Compilation Environment and Runtime Environment. + +The declarations in source files and previously compiled class files are analyzed +by `javac` in a _compilation environment_ that is distinct from the +_runtime environment_ used to execute `javac` itself. Although there is a +deliberate similarity between many `javac` options and like-named options for the +Java [launcher](java.html), such as `--class-path`, `--module-path` and so +on, it is important to understand that in general the `javac` options just affect +the environment in which the source files are compiled, and do not affect +the operation of `javac` itself. + +The distinction between the compilation environment and runtime environment +is significant when it comes to using annotation processors. +Although annotations processors process elements (declarations) that exist +in the compilation environment, the annotation processor itself is executed +in the runtime environment. If an annotation processor has dependencies on +libraries that are not in modules, the libraries can be placed, along with the +annotation processor itself, on the processor path. +(See the [`--processor-path`](#option-processor-path) option.) +If the annotation processor and its dependencies are in modules, you should +use the processor module path instead. +(See the [`--processor-module-path`](#option-processor-module-path) option.) +When those are insufficient, it may be necessary to provide further +configuration of the runtime environment. This can be done in two ways: + +1. If `javac` is invoked from the command line, options can be passed to the + underlying runtime by prefixing the option with [`-J`](#option-J). + +2. You can start an instance of a Java Virtual Machine directly and use + command line options and API to configure an environment in which + `javac` can be invoked via one of its [APIs]. + +## Compiling for Earlier Releases of the Platform + +`javac` can compile code that is to be used on other releases of the platform, +using either the [`--release`](#option-release) option, or the [`--source`](#option-source)/`-source` and +[`--target`](#option-target)/`-target` options, together with additional options to specify the +platform classes. + +Depending on the desired platform release, there are some restrictions on some +of the options that can be used. + +* When compiling for JDK 8 and earlier releases, you cannot use any option + that is intended for use with the module system. + This includes all of the following options: + + * [`--module-source-path`](#option-module-source-path), + [`--upgrade-module-path`](#option-upgrade-module-path), + [`--system`](#option-system), + [`--module-path`](#option-module-path), + [`--add-modules`](#option-add-modules), + [`--add-exports`](#option-add-exports), + `--add-opens`, + [`--add-reads`](#option-add-reads), + [`--limit-modules`](#option-limit-modules), + [`--patch-module`](#option-patch-module) + + If you use the `--source`/`-source` or `--target`/`-target` options, + you should also set the appropriate platform classes using the + boot class path family of options. + +* When compiling for JDK 9 and later releases, you cannot use any option + that is intended to configure the boot class path. + This includes all of the following options: + + * [`-Xbootclasspath/p:`](#option-Xbootclasspath-p), + [`-Xbootclasspath`](#option-Xbootclasspath), + [`-Xbootclasspath/a:`](#option-Xbootclasspath-a), + [`-endorseddirs`](#option-endorseddirs), + [`-Djava.endorsed.dirs`](#option-Djava.endorsed.dirs), + [`-extdirs`](#option-extdirs), + [`-Djava.ext.dirs`](#option-Djava.ext.dirs), + [`-profile`](#option-profile) + + If you use the `--source`/`-source` or `--target`/`-target` options, + you should also set the appropriate platform classes using the `--system` + option to give the location of an appropriate installed release of JDK. + +When using the `--release` option, only the supported documented API for that +release may be used; you cannot use any options to break encapsulation to +access any internal classes. + +## APIs + +The `javac` compiler can be invoked using an API in three different ways: + +The [Java Compiler API](../../api/java.compiler/javax/tools/JavaCompiler.html) +: This provides the most flexible way to invoke the compiler, + including the ability to compile source files provided in + memory buffers or other non-standard file systems. + +The [ToolProvider API](../../api/java.base/java/util/spi/ToolProvider.html) +: A `ToolProvider` for `javac` can be obtained by calling + `ToolProvider.findFirst("javac")`. This returns an object + with the equivalent functionality of the command-line tool. + + **Note**: This API should not be confused with the like-named + API in the [`javax.tools`](../../api/java.compiler/javax/tools/ToolProvider.html) + package. + +The `javac` [Legacy API](../../api/jdk.compiler/com/sun/tools/javac/Main.html) +: This API is retained for backward compatibility only. + All new code should use either the Java Compiler API or the ToolProvider API. + +**Note:** All other classes and methods found in a package with names that start with +`com.sun.tools.javac` (subpackages of `com.sun.tools.javac`) are strictly +internal and subject to change at any time. + +## Examples of Using -Xlint keys + +`cast` +: Warns about unnecessary and redundant casts, for example: + + > `String s = (String) "Hello!"` + +`classfile` +: Warns about issues related to class file contents. + +`deprecation` +: Warns about the use of deprecated items. For example: + + ``` + java.util.Date myDate = new java.util.Date(); + int currentDay = myDate.getDay(); + ``` + + The method `java.util.Date.getDay` has been deprecated since JDK 1.1. + +`dep-ann` +: Warns about items that are documented with the `@deprecated` Javadoc + comment, but do not have the `@Deprecated` annotation, for example: + + ``` + /** + * @deprecated As of Java SE 7, replaced by {@link #newMethod()} + */ + public static void deprecatedMethod() { } + public static void newMethod() { } + ``` + +`divzero` +: Warns about division by the constant integer 0, for example: + + > `int divideByZero = 42 / 0;` + +`empty` +: Warns about empty statements after `if`statements, for example: + + ``` + class E { + void m() { + if (true) ; + } + } + ``` + +`fallthrough` +: Checks the switch blocks for fall-through cases and provides a warning + message for any that are found. Fall-through cases are cases in a switch + block, other than the last case in the block, whose code does not include a + `break` statement, allowing code execution to fall through from that case to + the next case. For example, the code following the case 1 label in this + switch block does not end with a `break` statement: + + ``` + switch (x) { + case 1: + System.out.println("1"); + // No break statement here. + case 2: + System.out.println("2"); + } + ``` + + If the `-Xlint:fallthrough` option was used when compiling this code, then + the compiler emits a warning about possible fall-through into case, with + the line number of the case in question. + +`finally` +: Warns about `finally` clauses that cannot be completed normally, for + example: + + ``` + public static int m() { + try { + throw new NullPointerException(); + } catch (NullPointerException(); { + System.err.println("Caught NullPointerException."); + return 1; + } finally { + return 0; + } + } + ``` + + The compiler generates a warning for the `finally` block in this example. + When the `int` method is called, it returns a value of 0. A `finally` block + executes when the `try` block exits. In this example, when control is + transferred to the `catch` block, the `int` method exits. However, the + `finally` block must execute, so it's executed, even though control was + transferred outside the method. + +`options` +: Warns about issues that related to the use of command-line options. See + [Compiling for Earlier Releases of the Platform]. + +`overrides` +: Warns about issues related to method overrides. For example, consider the + following two classes: + + ``` + public class ClassWithVarargsMethod { + void varargsMethod(String... s) { } + } + + public class ClassWithOverridingMethod extends ClassWithVarargsMethod { + @Override + void varargsMethod(String[] s) { } + } + ``` + + The compiler generates a warning similar to the following:. + + ``` + warning: [override] varargsMethod(String[]) in ClassWithOverridingMethod + overrides varargsMethod(String...) in ClassWithVarargsMethod; overriding + method is missing '...' + ``` + + When the compiler encounters a `varargs` method, it translates the + `varargs` formal parameter into an array. In the method + `ClassWithVarargsMethod.varargsMethod`, the compiler translates the + `varargs` formal parameter `String... s` to the formal parameter + `String[] s`, an array that matches the formal parameter of the method + `ClassWithOverridingMethod.varargsMethod`. Consequently, this example + compiles. + +`path` +: Warns about invalid path elements and nonexistent path directories on the + command line (with regard to the class path, the source path, and other + paths). Such warnings cannot be suppressed with the `@SuppressWarnings` + annotation. For example: + + - **Linux and macOS:** + `javac -Xlint:path -classpath /nonexistentpath Example.java` + + - **Windows:** + `javac -Xlint:path -classpath C:\nonexistentpath Example.java` + +`processing` +: Warns about issues related to annotation processing. The compiler generates + this warning when you have a class that has an annotation, and you use an + annotation processor that cannot handle that type of annotation. For example, + the following is a simple annotation processor: + + **Source file AnnoProc.java**: + + ``` + import java.util.*; + import javax.annotation.processing.*; + import javax.lang.model.*; + import javax.lang.model.element.*; + + @SupportedAnnotationTypes("NotAnno") + public class AnnoProc extends AbstractProcessor { + public boolean process(Set elems, RoundEnvironment renv){ + return true; + } + + public SourceVersion getSupportedSourceVersion() { + return SourceVersion.latest(); + } + } + ``` + + **Source file AnnosWithoutProcessors.java**: + + ``` + @interface Anno { } + + @Anno + class AnnosWithoutProcessors { } + ``` + + The following commands compile the annotation processor `AnnoProc`, then + run this annotation processor against the source file + `AnnosWithoutProcessors.java`: + + ``` + javac AnnoProc.java + javac -cp . -Xlint:processing -processor AnnoProc -proc:only AnnosWithoutProcessors.java + ``` + + When the compiler runs the annotation processor against the source file + `AnnosWithoutProcessors.java`, it generates the following warning: + + ``` + warning: [processing] No processor claimed any of these annotations: Anno + ``` + + To resolve this issue, you can rename the annotation defined and used in + the class `AnnosWithoutProcessors` from `Anno` to `NotAnno`. + +`rawtypes` +: Warns about unchecked operations on raw types. The following statement + generates a `rawtypes` warning: + + > `void countElements(List l) { ... }` + + The following example does not generate a `rawtypes` warning: + + > `void countElements(List l) { ... }` + + `List` is a raw type. However, `List` is an unbounded wildcard + parameterized type. Because `List` is a parameterized interface, always + specify its type argument. In this example, the `List` formal argument is + specified with an unbounded wildcard (`?`) as its formal type parameter, + which means that the `countElements` method can accept any instantiation of + the `List` interface. + +`serial` +: Warns about missing `serialVersionUID` definitions on serializable classes. + For example: + + ``` + public class PersistentTime implements Serializable + { + private Date time; + + public PersistentTime() { + time = Calendar.getInstance().getTime(); + } + + public Date getTime() { + return time; + } + } + ``` + + The compiler generates the following warning: + + ``` + warning: [serial] serializable class PersistentTime has no definition of + serialVersionUID + ``` + + If a serializable class does not explicitly declare a field named + `serialVersionUID`, then the serialization runtime environment calculates a + default `serialVersionUID` value for that class based on various aspects of + the class, as described in the Java Object Serialization Specification. + However, it's strongly recommended that all serializable classes explicitly + declare `serialVersionUID` values because the default process of computing + `serialVersionUID` values is highly sensitive to class details that can + vary depending on compiler implementations. As a result, this might cause + an unexpected `InvalidClassExceptions` during deserialization. To guarantee + a consistent `serialVersionUID` value across different Java compiler + implementations, a serializable class must declare an explicit + `serialVersionUID` value. + +`static` +: Warns about issues relating to the use of static variables, for example: + + ``` + class XLintStatic { + static void m1() { } + void m2() { this.m1(); } + } + ``` + + The compiler generates the following warning: + + ``` + warning: [static] static method should be qualified by type name, + XLintStatic, instead of by an expression + ``` + + To resolve this issue, you can call the `static` method `m1` as follows: + + > `XLintStatic.m1();` + + Alternately, you can remove the `static` keyword from the declaration of + the method `m1`. + +`this-escape` +: Warns about constructors leaking + `this` prior to subclass initialization. + For example, this class: + + ``` + public class MyClass { + public MyClass() { + System.out.println(this.hashCode()); + } + } + ``` + + generates the following warning: + + ``` + MyClass.java:3: warning: [this-escape] possible 'this' escape + before subclass is fully initialized + System.out.println(this.hashCode()); + ^ + ``` + + A 'this' escape warning is generated when a constructor does something + that might result in a subclass method being invoked before the + constructor returns. + In such cases the subclass method would be operating on an incompletely + initialized instance. + In the above example, a subclass of `MyClass` that overrides + `hashCode()` to incorporate its own fields would likely produce + an incorrect result when invoked as shown. + + Warnings are only generated if a subclass could exist that is outside + of the current module (or package, if no module) being compiled. + So, for example, constructors in final and non-public classes do not + generate warnings. + +`try` +: Warns about issues relating to the use of `try` blocks, including + try-with-resources statements. For example, a warning is generated for the + following statement because the resource `ac` declared in the `try` block + is not used: + + ``` + try ( AutoCloseable ac = getResource() ) { // do nothing} + ``` + +`unchecked` +: Gives more detail for unchecked conversion warnings that are mandated by + the Java Language Specification, for example: + + ``` + List l = new ArrayList(); + List ls = l; // unchecked warning + ``` + + During type erasure, the types `ArrayList` and `List` + become `ArrayList` and `List`, respectively. + + The `ls` command has the parameterized type `List`. When the `List` + referenced by `l` is assigned to `ls`, the compiler generates an unchecked + warning. At compile time, the compiler and JVM cannot determine whether `l` + refers to a `List` type. In this case, `l` does not refer to a + `List` type. As a result, heap pollution occurs. + + A heap pollution situation occurs when the `List` object `l`, whose static + type is `List`, is assigned to another `List` object, `ls`, that + has a different static type, `List`. However, the compiler still + allows this assignment. It must allow this assignment to preserve backward + compatibility with releases of Java SE that do not support generics. Because + of type erasure, `List` and `List` both become `List`. + Consequently, the compiler allows the assignment of the object `l`, which + has a raw type of `List`, to the object `ls`. + +`varargs` +: Warns about unsafe use of variable arguments (`varargs`) methods, in + particular, those that contain non-reifiable arguments, for example: + + ``` + public class ArrayBuilder { + public static void addToList (List listArg, T... elements) { + for (T x : elements) { + listArg.add(x); + } + } + } + ``` + + A non-reifiable type is a type whose type information is not fully available + at runtime. + + The compiler generates the following warning for the definition of the + method `ArrayBuilder.addToList`: + + ``` + warning: [varargs] Possible heap pollution from parameterized vararg type T + ``` + + When the compiler encounters a varargs method, it translates the `varargs` + formal parameter into an array. However, the Java programming language + does not permit the creation of arrays of parameterized types. In the method + `ArrayBuilder.addToList`, the compiler translates the `varargs` formal + parameter `T...` elements to the formal parameter `T[]` elements, an array. + However, because of type erasure, the compiler converts the `varargs` + formal parameter to `Object[]` elements. Consequently, there's a + possibility of heap pollution. diff --git a/src/jdk.compiler/share/man/serialver.1 b/src/jdk.compiler/share/man/serialver.1 deleted file mode 100644 index bad14872ee6..00000000000 --- a/src/jdk.compiler/share/man/serialver.1 +++ /dev/null @@ -1,90 +0,0 @@ -.\" Copyright (c) 1997, 2018, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "SERIALVER" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -serialver - return the \f[V]serialVersionUID\f[R] for one or more -classes in a form suitable for copying into an evolving class -.SH SYNOPSIS -.PP -\f[V]serialver\f[R] [\f[I]options\f[R]] [\f[I]classnames\f[R]] -.TP -\f[I]options\f[R] -This represents the command-line options for the \f[V]serialver\f[R] -command. -See \f[B]Options for serialver\f[R]. -.TP -\f[I]classnames\f[R] -The classes for which \f[V]serialVersionUID\f[R] is to be returned. -.SH DESCRIPTION -.PP -The \f[V]serialver\f[R] command returns the \f[V]serialVersionUID\f[R] -for one or more classes in a form suitable for copying into an evolving -class. -When called with no arguments, the \f[V]serialver\f[R] command prints a -usage line. -.SH OPTIONS FOR SERIALVER -.TP -\f[V]-classpath\f[R] \f[I]path-files\f[R] -Sets the search path for application classes and resources. -Separate classes and resources with a colon (:). -.TP -\f[V]-J\f[R]\f[I]option\f[R] -Passes the specified \f[I]option\f[R] to the Java Virtual Machine, where -\f[I]option\f[R] is one of the options described on the reference page -for the Java application launcher. -For example, \f[V]-J-Xms48m\f[R] sets the startup memory to 48 MB. -.SH NOTES -.PP -The \f[V]serialver\f[R] command loads and initializes the specified -classes in its virtual machine, and by default, it doesn\[aq]t set a -security manager. -If the \f[V]serialver\f[R] command is to be run with untrusted classes, -then a security manager can be set with the following option: -.RS -.PP -\f[V]-J-Djava.security.manager\f[R] -.RE -.PP -When necessary, a security policy can be specified with the following -option: -.RS -.PP -\f[V]-J-Djava.security.policy=\f[R]\f[I]policy_file\f[R] -.RE diff --git a/src/jdk.compiler/share/man/serialver.md b/src/jdk.compiler/share/man/serialver.md new file mode 100644 index 00000000000..5838f1c61a9 --- /dev/null +++ b/src/jdk.compiler/share/man/serialver.md @@ -0,0 +1,74 @@ +--- +# Copyright (c) 1997, 2018, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'SERIALVER(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +serialver - return the `serialVersionUID` for one or more classes in a form +suitable for copying into an evolving class + +## Synopsis + +`serialver` \[*options*\] \[*classnames*\] + +*options* +: This represents the command-line options for the `serialver` command. See + [Options for serialver]. + +*classnames* +: The classes for which `serialVersionUID` is to be returned. + +## Description + +The `serialver` command returns the `serialVersionUID` for one or more classes +in a form suitable for copying into an evolving class. When called with no +arguments, the `serialver` command prints a usage line. + +## Options for serialver + +`-classpath` *path-files* +: Sets the search path for application classes and resources. Separate + classes and resources with a colon (:). + +`-J`*option* +: Passes the specified *option* to the Java Virtual Machine, where *option* + is one of the options described on the reference page for the Java + application launcher. For example, `-J-Xms48m` sets the startup memory to + 48 MB. + +## Notes + +The `serialver` command loads and initializes the specified classes in its +virtual machine, and by default, it doesn't set a security manager. If the +`serialver` command is to be run with untrusted classes, then a security +manager can be set with the following option: + +> `-J-Djava.security.manager` + +When necessary, a security policy can be specified with the following option: + +> `-J-Djava.security.policy=`*policy\_file* diff --git a/src/jdk.hotspot.agent/share/man/jhsdb.1 b/src/jdk.hotspot.agent/share/man/jhsdb.1 deleted file mode 100644 index 93cc1fedb15..00000000000 --- a/src/jdk.hotspot.agent/share/man/jhsdb.1 +++ /dev/null @@ -1,218 +0,0 @@ -.\" Copyright (c) 2019, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JHSDB" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -jhsdb - attach to a Java process or launch a postmortem debugger to -analyze the content of a core dump from a crashed Java Virtual Machine -(JVM) -.SH SYNOPSIS -.PP -\f[B]WARNING:\f[R] The \f[V]debugd\f[R] subcommand and -\f[V]--connect\f[R] options are deprecated. -They will be removed in a future release. -.PP -\f[V]jhsdb\f[R] \f[V]clhsdb\f[R] [\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] -\f[I]coredump\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]hsdb\f[R] [\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] -\f[I]coredump\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]debugd\f[R] (\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] -\f[I]coredump\f[R]) [\f[I]options\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]jstack\f[R] (\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] \f[I]coredump\f[R] -| \f[V]--connect\f[R] \f[I][server-id\[at]]debugd-host\f[R]) -[\f[I]options\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]jmap\f[R] (\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] \f[I]coredump\f[R] -| \f[V]--connect\f[R] \f[I][server-id\[at]]debugd-host\f[R]) -[\f[I]options\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]jinfo\f[R] (\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] \f[I]coredump\f[R] -| \f[V]--connect\f[R] \f[I][server-id\[at]]debugd-host\f[R]) -[\f[I]options\f[R]] -.PP -\f[V]jhsdb\f[R] \f[V]jsnap\f[R] (\f[V]--pid\f[R] \f[I]pid\f[R] | -\f[V]--exe\f[R] \f[I]executable\f[R] \f[V]--core\f[R] \f[I]coredump\f[R] -| \f[V]--connect\f[R] \f[I][server-id\[at]]debugd-host\f[R]) -[\f[I]options\f[R]] -.TP -\f[I]pid\f[R] -The process ID to which the \f[V]jhsdb\f[R] tool should attach. -The process must be a Java process. -To get a list of Java processes running on a machine, use the -\f[V]ps\f[R] command or, if the JVM processes are not running in a -separate docker instance, the \f[B]jps\f[R] command. -.TP -\f[I]executable\f[R] -The Java executable file from which the core dump was produced. -.TP -\f[I]coredump\f[R] -The core file to which the \f[V]jhsdb\f[R] tool should attach. -.TP -\f[I][server-id\[at]]debugd-host\f[R] -An optional server ID and the address of the remote debug server -(debugd). -.TP -\f[I]options\f[R] -The command-line options for a \f[V]jhsdb\f[R] mode. -See \f[B]Options for the debugd Mode\f[R], \f[B]Options for the jstack -Mode\f[R], \f[B]Options for the jmap Mode\f[R], \f[B]Options for the -jinfo Mode\f[R], and \f[B]Options for the jsnap Mode\f[R]. -.PP -\f[B]Note:\f[R] -.PP -Either the \f[I]pid\f[R] or the pair of \f[I]executable\f[R] and -\f[I]core\f[R] files or the \f[I][server-id\[at]]debugd-host\f[R] must -be provided for \f[V]debugd\f[R], \f[V]jstack\f[R], \f[V]jmap\f[R], -\f[V]jinfo\f[R] and \f[V]jsnap\f[R] modes. -.SH DESCRIPTION -.PP -You can use the \f[V]jhsdb\f[R] tool to attach to a Java process or to -launch a postmortem debugger to analyze the content of a core-dump from -a crashed Java Virtual Machine (JVM). -This command is experimental and unsupported. -.PP -\f[B]Note:\f[R] -.PP -Attaching the \f[V]jhsdb\f[R] tool to a live process will cause the -process to hang and the process will probably crash when the debugger -detaches. -.PP -The \f[V]jhsdb\f[R] tool can be launched in any one of the following -modes: -.TP -\f[V]jhsdb clhsdb\f[R] -Starts the interactive command-line debugger. -.TP -\f[V]jhsdb hsdb\f[R] -Starts the interactive GUI debugger. -.TP -\f[V]jhsdb debugd\f[R] -Starts the remote debug server. -.TP -\f[V]jhsdb jstack\f[R] -Prints stack and locks information. -.TP -\f[V]jhsdb jmap\f[R] -Prints heap information. -.TP -\f[V]jhsdb jinfo\f[R] -Prints basic JVM information. -.TP -\f[V]jhsdb jsnap\f[R] -Prints performance counter information. -.TP -\f[V]jhsdb\f[R] \f[I]command\f[R] \f[V]--help\f[R] -Displays the options available for the \f[I]command\f[R]. -.SH OPTIONS FOR THE DEBUGD MODE -.TP -\f[V]--serverid\f[R] \f[I]server-id\f[R] -An optional unique ID for this debug server. -This is required if multiple debug servers are run on the same machine. -.TP -\f[V]--rmiport\f[R] \f[I]port\f[R] -Sets the port number to which the RMI connector is bound. -If not specified a random available port is used. -.TP -\f[V]--registryport\f[R] \f[I]port\f[R] -Sets the RMI registry port. -This option overrides the system property -\[aq]sun.jvm.hotspot.rmi.port\[aq]. -If not specified, the system property is used. -If the system property is not set, the default port 1099 is used. -.TP -\f[V]--hostname\f[R] \f[I]hostname\f[R] -Sets the hostname the RMI connector is bound. -The value could be a hostname or an IPv4/IPv6 address. -This option overrides the system property -\[aq]java.rmi.server.hostname\[aq]. -If not specified, the system property is used. -If the system property is not set, a system hostname is used. -.SH OPTIONS FOR THE JINFO MODE -.TP -\f[V]--flags\f[R] -Prints the VM flags. -.TP -\f[V]--sysprops\f[R] -Prints the Java system properties. -.TP -no option -Prints the VM flags and the Java system properties. -.SH OPTIONS FOR THE JMAP MODE -.TP -no option -Prints the same information as Solaris \f[V]pmap\f[R]. -.TP -\f[V]--heap\f[R] -Prints the \f[V]java\f[R] heap summary. -.TP -\f[V]--binaryheap\f[R] -Dumps the \f[V]java\f[R] heap in \f[V]hprof\f[R] binary format. -.TP -\f[V]--dumpfile\f[R] \f[I]name\f[R] -The name of the dumpfile. -.TP -\f[V]--histo\f[R] -Prints the histogram of \f[V]java\f[R] object heap. -.TP -\f[V]--clstats\f[R] -Prints the class loader statistics. -.TP -\f[V]--finalizerinfo\f[R] -Prints the information on objects awaiting finalization. -.SH OPTIONS FOR THE JSTACK MODE -.TP -\f[V]--locks\f[R] -Prints the \f[V]java.util.concurrent\f[R] locks information. -.TP -\f[V]--mixed\f[R] -Attempts to print both \f[V]java\f[R] and native frames if the platform -allows it. -.SH OPTIONS FOR THE JSNAP MODE -.TP -\f[V]--all\f[R] -Prints all performance counters. diff --git a/src/jdk.hotspot.agent/share/man/jhsdb.md b/src/jdk.hotspot.agent/share/man/jhsdb.md new file mode 100644 index 00000000000..4c6be775ece --- /dev/null +++ b/src/jdk.hotspot.agent/share/man/jhsdb.md @@ -0,0 +1,186 @@ +--- +# Copyright (c) 2019, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JHSDB(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jhsdb - attach to a Java process or launch a postmortem debugger to analyze +the content of a core dump from a crashed Java Virtual Machine (JVM) + +## Synopsis + + **WARNING:** The `debugd` subcommand and `--connect` options are deprecated. They will be removed in a future release. + +`jhsdb` `clhsdb` \[`--pid` *pid* \| `--exe` *executable* `--core` *coredump*\] + +`jhsdb` `hsdb` \[`--pid` *pid* \| `--exe` *executable* `--core` *coredump*\] + +`jhsdb` `debugd` (`--pid` *pid* \| `--exe` *executable* `--core` *coredump*) +\[*options*\] + +`jhsdb` `jstack` (`--pid` *pid* \| `--exe` *executable* `--core` *coredump* \| +`--connect` *\[server-id@\]debugd-host*) \[*options*\] + +`jhsdb` `jmap` (`--pid` *pid* \| `--exe` *executable* `--core` *coredump* \| +`--connect` *\[server-id@\]debugd-host*) \[*options*\] + +`jhsdb` `jinfo` (`--pid` *pid* \| `--exe` *executable* `--core` *coredump* \| +`--connect` *\[server-id@\]debugd-host*) \[*options*\] + +`jhsdb` `jsnap` (`--pid` *pid* \| `--exe` *executable* `--core` *coredump* \| +`--connect` *\[server-id@\]debugd-host*) \[*options*\] + +*pid* +: The process ID to which the `jhsdb` tool should attach. The process must be + a Java process. To get a list of Java processes running on a machine, use + the `ps` command or, if the JVM processes are not running in a separate + docker instance, the [jps](jps.html) command. + +*executable* +: The Java executable file from which the core dump was produced. + +*coredump* +: The core file to which the `jhsdb` tool should attach. + +*\[server-id@\]debugd-host* +: An optional server ID and the address of the remote debug server (debugd). + +*options* +: The command-line options for a `jhsdb` mode. See [Options for the debugd Mode], + [Options for the jstack Mode], [Options for the jmap Mode], + [Options for the jinfo Mode], and [Options for the jsnap Mode]. + +**Note:** + +Either the *pid* or the pair of *executable* and *core* files or +the *\[server-id@\]debugd-host* must be provided for `debugd`, `jstack`, `jmap`, +`jinfo` and `jsnap` modes. + +## Description + +You can use the `jhsdb` tool to attach to a Java process or to launch a +postmortem debugger to analyze the content of a core-dump from a crashed Java +Virtual Machine (JVM). This command is experimental and unsupported. + +**Note:** + +Attaching the `jhsdb` tool to a live process will cause the process to hang and +the process will probably crash when the debugger detaches. + +The `jhsdb` tool can be launched in any one of the following modes: + +`jhsdb clhsdb` +: Starts the interactive command-line debugger. + +`jhsdb hsdb` +: Starts the interactive GUI debugger. + +`jhsdb debugd` +: Starts the remote debug server. + +`jhsdb jstack` +: Prints stack and locks information. + +`jhsdb jmap` +: Prints heap information. + +`jhsdb jinfo` +: Prints basic JVM information. + +`jhsdb jsnap` +: Prints performance counter information. + +`jhsdb` *command* `--help` +: Displays the options available for the *command*. + +## Options for the debugd Mode + +`--serverid` *server-id* +: An optional unique ID for this debug server. This is required if multiple + debug servers are run on the same machine. + +`--rmiport` *port* +: Sets the port number to which the RMI connector is bound. If not specified + a random available port is used. + +`--registryport` *port* +: Sets the RMI registry port. This option overrides the system property + 'sun.jvm.hotspot.rmi.port'. If not specified, the system property is used. + If the system property is not set, the default port 1099 is used. + +`--hostname` *hostname* +: Sets the hostname the RMI connector is bound. The value could be a hostname + or an IPv4/IPv6 address. This option overrides the system property + 'java.rmi.server.hostname'. If not specified, the system property is used. + If the system property is not set, a system hostname is used. + +## Options for the jinfo Mode + +`--flags` +: Prints the VM flags. + +`--sysprops` +: Prints the Java system properties. + +no option +: Prints the VM flags and the Java system properties. + +## Options for the jmap Mode + +no option +: Prints the same information as Solaris `pmap`. + +`--heap` +: Prints the `java` heap summary. + +`--binaryheap` +: Dumps the `java` heap in `hprof` binary format. + +`--dumpfile` *name* +: The name of the dumpfile. + +`--histo` +: Prints the histogram of `java` object heap. + +`--clstats` +: Prints the class loader statistics. + +`--finalizerinfo` +: Prints the information on objects awaiting finalization. + +## Options for the jstack Mode + +`--locks` +: Prints the `java.util.concurrent` locks information. + +`--mixed` +: Attempts to print both `java` and native frames if the platform allows it. + +## Options for the jsnap Mode + +`--all` +: Prints all performance counters. diff --git a/src/jdk.httpserver/share/man/jwebserver.1 b/src/jdk.httpserver/share/man/jwebserver.1 deleted file mode 100644 index 4fbaf9dd09d..00000000000 --- a/src/jdk.httpserver/share/man/jwebserver.1 +++ /dev/null @@ -1,193 +0,0 @@ -.\" Copyright (c) 2021, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JWEBSERVER" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -jwebserver - launch the Java Simple Web Server -.SH SYNOPSIS -.PP -\f[V]jwebserver\f[R] [\f[I]options\f[R]] -.TP -\f[I]options\f[R] -Command-line options. -For a detailed description of the options, see \f[B]Options\f[R]. -.SH DESCRIPTION -.PP -The \f[V]jwebserver\f[R] tool provides a minimal HTTP server, designed -to be used for prototyping, testing, and debugging. -It serves a single directory hierarchy, and only serves static files. -Only HTTP/1.1 is supported; HTTP/2 and HTTPS are not supported. -.PP -Only idempotent HEAD and GET requests are served. -Any other requests receive a \f[V]501 - Not Implemented\f[R] or a -\f[V]405 - Not Allowed\f[R] response. -GET requests are mapped to the directory being served, as follows: -.IP \[bu] 2 -If the requested resource is a file, its content is served. -.IP \[bu] 2 -If the requested resource is a directory that contains an index file, -the content of the index file is served. -.IP \[bu] 2 -Otherwise, the names of all files and subdirectories of the directory -are listed. -Symbolic links and hidden files are not listed or served. -.PP -MIME types are configured automatically, using the built-in table. -For example, \f[V].html\f[R] files are served as \f[V]text/html\f[R] and -\f[V].java\f[R] files are served as \f[V]text/plain\f[R]. -.PP -\f[V]jwebserver\f[R] is located in the jdk.httpserver module, and can -alternatively be started with \f[V]java -m jdk.httpserver\f[R]. -It is based on the web server implementation in the -\f[V]com.sun.net.httpserver\f[R] package. -The \f[V]com.sun.net.httpserver.SimpleFileServer\f[R] class provides a -programmatic way to retrieve the server and its components for reuse and -extension. -.SH USAGE -.IP -.nf -\f[CB] -jwebserver [-b bind address] [-p port] [-d directory] - [-o none|info|verbose] [-h to show options] - [-version to show version information] -\f[R] -.fi -.SH OPTIONS -.TP -\f[V]-h\f[R] or \f[V]-?\f[R] or \f[V]--help\f[R] -Prints the help message and exits. -.TP -\f[V]-b\f[R] \f[I]addr\f[R] or \f[V]--bind-address\f[R] \f[I]addr\f[R] -Specifies the address to bind to. -Default: 127.0.0.1 or ::1 (loopback). -For all interfaces use \f[V]-b 0.0.0.0\f[R] or \f[V]-b ::\f[R]. -.TP -\f[V]-d\f[R] \f[I]dir\f[R] or \f[V]--directory\f[R] \f[I]dir\f[R] -Specifies the directory to serve. -Default: current directory. -.TP -\f[V]-o\f[R] \f[I]level\f[R] or \f[V]--output\f[R] \f[I]level\f[R] -Specifies the output format. -\f[V]none\f[R] | \f[V]info\f[R] | \f[V]verbose\f[R]. -Default: \f[V]info\f[R]. -.TP -\f[V]-p\f[R] \f[I]port\f[R] or \f[V]--port\f[R] \f[I]port\f[R] -Specifies the port to listen on. -Default: 8000. -.TP -\f[V]-version\f[R] or \f[V]--version\f[R] -Prints the version information and exits. -.PP -To stop the server, press \f[V]Ctrl + C\f[R]. -.SH STARTING THE SERVER -.PP -The following command starts the Simple Web Server: -.IP -.nf -\f[CB] -$ jwebserver -\f[R] -.fi -.PP -If startup is successful, the server prints a message to -\f[V]System.out\f[R] listing the local address and the absolute path of -the directory being served. -For example: -.IP -.nf -\f[CB] -$ jwebserver -Binding to loopback by default. For all interfaces use \[dq]-b 0.0.0.0\[dq] or \[dq]-b ::\[dq]. -Serving /cwd and subdirectories on 127.0.0.1 port 8000 -URL http://127.0.0.1:8000/ -\f[R] -.fi -.SH CONFIGURATION -.PP -By default, the server runs in the foreground and binds to the loopback -address and port 8000. -This can be changed with the \f[V]-b\f[R] and \f[V]-p\f[R] options. -For example, to bind the Simple Web Server to all interfaces, use: -.IP -.nf -\f[CB] -$ jwebserver -b 0.0.0.0 -Serving /cwd and subdirectories on 0.0.0.0 (all interfaces) port 8000 -URL http://123.456.7.891:8000/ -\f[R] -.fi -.PP -Note that this makes the web server accessible to all hosts on the -network. -\f[I]Do not do this unless you are sure the server cannot leak any -sensitive information.\f[R] -.PP -As another example, use the following command to run on port 9000: -.IP -.nf -\f[CB] -$ jwebserver -p 9000 -\f[R] -.fi -.PP -By default, the files of the current directory are served. -A different directory can be specified with the \f[V]-d\f[R] option. -.PP -By default, every request is logged on the console. -The output looks like this: -.IP -.nf -\f[CB] -127.0.0.1 - - [10/Feb/2021:14:34:11 +0000] \[dq]GET /some/subdirectory/ HTTP/1.1\[dq] 200 - -\f[R] -.fi -.PP -Logging output can be changed with the \f[V]-o\f[R] option. -The default setting is \f[V]info\f[R]. -The \f[V]verbose\f[R] setting additionally includes the request and -response headers as well as the absolute path of the requested resource. -.SH STOPPING THE SERVER -.PP -Once started successfully, the server runs until it is stopped. -On Unix platforms, the server can be stopped by sending it a -\f[V]SIGINT\f[R] signal (\f[V]Ctrl+C\f[R] in a terminal window). -.SH HELP OPTION -.PP -The \f[V]-h\f[R] option displays a help message describing the usage and -the options of the \f[V]jwebserver\f[R]. diff --git a/src/jdk.httpserver/share/man/jwebserver.md b/src/jdk.httpserver/share/man/jwebserver.md new file mode 100644 index 00000000000..352e982654d --- /dev/null +++ b/src/jdk.httpserver/share/man/jwebserver.md @@ -0,0 +1,152 @@ +--- +# Copyright (c) 2021, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JWEBSERVER(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jwebserver - launch the Java Simple Web Server + +## Synopsis + +`jwebserver` \[*options*\] + +*options* +: Command-line options. For a detailed description of the options, see [Options]. + +## Description +The `jwebserver` tool provides a minimal HTTP server, designed to be used +for prototyping, testing, and debugging. It serves a single directory hierarchy, +and only serves static files. Only HTTP/1.1 is supported; +HTTP/2 and HTTPS are not supported. + +Only idempotent HEAD and GET requests are served. Any other requests receive +a `501 - Not Implemented` or a `405 - Not Allowed` response. GET requests are +mapped to the directory being served, as follows: + +* If the requested resource is a file, its content is served. +* If the requested resource is a directory that contains an index file, +the content of the index file is served. +* Otherwise, the names of all files and subdirectories of the directory are +listed. Symbolic links and hidden files are not listed or served. + +MIME types are configured automatically, using the built-in table. For example, +`.html` files are served as `text/html` and `.java` files are served as +`text/plain`. + +`jwebserver` is located in the jdk.httpserver module, and can alternatively +be started with `java -m jdk.httpserver`. It is based on the web server +implementation in the `com.sun.net.httpserver` package. +The `com.sun.net.httpserver.SimpleFileServer` class provides a programmatic +way to retrieve the server and its components for reuse and extension. + +## Usage +``` +jwebserver [-b bind address] [-p port] [-d directory] + [-o none|info|verbose] [-h to show options] + [-version to show version information] +``` + +## Options + +`-h` or `-?` or `--help` +: Prints the help message and exits. + +`-b` *addr* or `--bind-address` *addr* +: Specifies the address to bind to. + Default: 127.0.0.1 or ::1 (loopback). + For all interfaces use `-b 0.0.0.0` or `-b ::`. + +`-d` *dir* or `--directory` *dir* +: Specifies the directory to serve. + Default: current directory. + +`-o` *level* or `--output` *level* +: Specifies the output format. `none` | `info` | `verbose`. + Default: `info`. + +`-p` *port* or `--port` *port* +: Specifies the port to listen on. + Default: 8000. + +`-version` or `--version` +: Prints the version information and exits. + +To stop the server, press `Ctrl + C`. + +## Starting the Server +The following command starts the Simple Web Server: +``` +$ jwebserver +``` +If startup is successful, the server prints a message to `System.out` +listing the local address and the absolute path of the directory being +served. For example: +``` +$ jwebserver +Binding to loopback by default. For all interfaces use "-b 0.0.0.0" or "-b ::". +Serving /cwd and subdirectories on 127.0.0.1 port 8000 +URL http://127.0.0.1:8000/ +``` + +## Configuration +By default, the server runs in the foreground and binds to the loopback +address and port 8000. This can be changed with the `-b` and `-p` options. +For example, to bind the Simple Web Server to all interfaces, use: +``` +$ jwebserver -b 0.0.0.0 +Serving /cwd and subdirectories on 0.0.0.0 (all interfaces) port 8000 +URL http://123.456.7.891:8000/ +``` +Note that this makes the web server accessible to all hosts on the network. +*Do not do this unless you are sure the server cannot leak any sensitive +information.* + +As another example, use the following command to run on port 9000: +``` +$ jwebserver -p 9000 +``` + +By default, the files of the current directory are served. A different +directory can be specified with the `-d` option. + +By default, every request is logged on the console. The output looks like +this: +``` +127.0.0.1 - - [10/Feb/2021:14:34:11 +0000] "GET /some/subdirectory/ HTTP/1.1" 200 - +``` +Logging output can be changed with the `-o` option. The default setting is +`info`. The `verbose` setting additionally includes the request and response +headers as well as the absolute path of the requested resource. + +## Stopping the Server +Once started successfully, the server runs until it is stopped. On Unix +platforms, the server can be stopped by sending it a `SIGINT` signal +(`Ctrl+C` in a terminal window). + +## Help Option +The `-h` option displays a help message describing the usage and the options +of the `jwebserver`. diff --git a/src/jdk.jartool/share/man/jar.1 b/src/jdk.jartool/share/man/jar.1 deleted file mode 100644 index a88653753ee..00000000000 --- a/src/jdk.jartool/share/man/jar.1 +++ /dev/null @@ -1,379 +0,0 @@ -.\" Copyright (c) 1997, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JAR" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -jar - create an archive for classes and resources, and manipulate or -restore individual classes or resources from an archive -.SH SYNOPSIS -.PP -\f[V]jar\f[R] [\f[I]OPTION\f[R] ...] -[ [\f[V]--release\f[R] \f[I]VERSION\f[R]] [\f[V]-C\f[R] \f[I]dir\f[R]] -\f[I]files\f[R]] ... -.SH DESCRIPTION -.PP -The \f[V]jar\f[R] command is a general-purpose archiving and compression -tool, based on the ZIP and ZLIB compression formats. -Initially, the \f[V]jar\f[R] command was designed to package Java -applets (not supported since JDK 11) or applications; however, beginning -with JDK 9, users can use the \f[V]jar\f[R] command to create modular -JARs. -For transportation and deployment, it\[aq]s usually more convenient to -package modules as modular JARs. -.PP -The syntax for the \f[V]jar\f[R] command resembles the syntax for the -\f[V]tar\f[R] command. -It has several main operation modes, defined by one of the mandatory -operation arguments. -Other arguments are either options that modify the behavior of the -operation or are required to perform the operation. -.PP -When modules or the components of an application (files, images and -sounds) are combined into a single archive, they can be downloaded by a -Java agent (such as a browser) in a single HTTP transaction, rather than -requiring a new connection for each piece. -This dramatically improves download times. -The \f[V]jar\f[R] command also compresses files, which further improves -download time. -The \f[V]jar\f[R] command also enables individual entries in a file to -be signed so that their origin can be authenticated. -A JAR file can be used as a class path entry, whether or not it\[aq]s -compressed. -.PP -An archive becomes a modular JAR when you include a module descriptor, -\f[V]module-info.class\f[R], in the root of the given directories or in -the root of the \f[V].jar\f[R] archive. -The following operations described in \f[B]Operation Modifiers Valid -Only in Create and Update Modes\f[R] are valid only when creating or -updating a modular jar or updating an existing non-modular jar: -.IP \[bu] 2 -\f[V]--module-version\f[R] -.IP \[bu] 2 -\f[V]--hash-modules\f[R] -.IP \[bu] 2 -\f[V]--module-path\f[R] -.PP -\f[B]Note:\f[R] -.PP -All mandatory or optional arguments for long options are also mandatory -or optional for any corresponding short options. -.SH MAIN OPERATION MODES -.PP -When using the \f[V]jar\f[R] command, you must specify the operation for -it to perform. -You specify the operation mode for the \f[V]jar\f[R] command by -including the appropriate operation arguments described in this section. -You can mix an operation argument with other one-letter options. -Generally the operation argument is the first argument specified on the -command line. -.TP -\f[V]-c\f[R] or \f[V]--create\f[R] -Creates the archive. -.TP -\f[V]-i\f[R] \f[I]FILE\f[R] or \f[V]--generate-index=\f[R]\f[I]FILE\f[R] -Generates index information for the specified JAR file. -This option is deprecated and may be removed in a future release. -.TP -\f[V]-t\f[R] or \f[V]--list\f[R] -Lists the table of contents for the archive. -.TP -\f[V]-u\f[R] or \f[V]--update\f[R] -Updates an existing JAR file. -.TP -\f[V]-x\f[R] or \f[V]--extract\f[R] -Extracts the named (or all) files from the archive. -If a file with the same name appears more than once in the archive, each -copy will be extracted, with later copies overwriting (replacing) -earlier copies unless -k is specified. -.TP -\f[V]-d\f[R] or \f[V]--describe-module\f[R] -Prints the module descriptor or automatic module name. -.SH OPERATION MODIFIERS VALID IN ANY MODE -.PP -You can use the following options to customize the actions of any -operation mode included in the \f[V]jar\f[R] command. -.TP -\f[V]-C\f[R] \f[I]DIR\f[R] -When used with the create operation mode, changes the specified -directory and includes the \f[I]files\f[R] specified at the end of the -command line. -.RS -.PP -\f[V]jar\f[R] [\f[I]OPTION\f[R] ...] -[ [\f[V]--release\f[R] \f[I]VERSION\f[R]] [\f[V]-C\f[R] \f[I]dir\f[R]] -\f[I]files\f[R]] -.PP -When used with the extract operation mode, specifies the destination -directory where the JAR file will be extracted. -Unlike with the create operation mode, this option can be specified only -once with the extract operation mode. -.RE -.TP -\f[V]-f\f[R] \f[I]FILE\f[R] or \f[V]--file=\f[R]\f[I]FILE\f[R] -Specifies the archive file name. -.TP -\f[V]--release\f[R] \f[I]VERSION\f[R] -Creates a multirelease JAR file. -Places all files specified after the option into a versioned directory -of the JAR file named -\f[V]META-INF/versions/\f[R]\f[I]VERSION\f[R]\f[V]/\f[R], where -\f[I]VERSION\f[R] must be must be a positive integer whose value is 9 or -greater. -.RS -.PP -At run time, where more than one version of a class exists in the JAR, -the JDK will use the first one it finds, searching initially in the -directory tree whose \f[I]VERSION\f[R] number matches the JDK\[aq]s -major version number. -It will then look in directories with successively lower -\f[I]VERSION\f[R] numbers, and finally look in the root of the JAR. -.RE -.TP -\f[V]-v\f[R] or \f[V]--verbose\f[R] -Sends or prints verbose output to standard output. -.SH OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES -.PP -You can use the following options to customize the actions of the create -and the update main operation modes: -.TP -\f[V]-e\f[R] \f[I]CLASSNAME\f[R] or \f[V]--main-class=\f[R]\f[I]CLASSNAME\f[R] -Specifies the application entry point for standalone applications -bundled into a modular or executable modular JAR file. -.TP -\f[V]-m\f[R] \f[I]FILE\f[R] or \f[V]--manifest=\f[R]\f[I]FILE\f[R] -Includes the manifest information from the given manifest file. -.TP -\f[V]-M\f[R] or \f[V]--no-manifest\f[R] -Doesn\[aq]t create a manifest file for the entries. -.TP -\f[V]--module-version=\f[R]\f[I]VERSION\f[R] -Specifies the module version, when creating or updating a modular JAR -file, or updating a non-modular JAR file. -.TP -\f[V]--hash-modules=\f[R]\f[I]PATTERN\f[R] -Computes and records the hashes of modules matched by the given pattern -and that depend upon directly or indirectly on a modular JAR file being -created or a non-modular JAR file being updated. -.TP -\f[V]-p\f[R] or \f[V]--module-path\f[R] -Specifies the location of module dependence for generating the hash. -.TP -\f[V]\[at]\f[R]\f[I]file\f[R] -Reads \f[V]jar\f[R] options and file names from a text file as if they -were supplied on the command line -.SH OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND GENERATE-INDEX MODES -.PP -You can use the following options to customize the actions of the create -(\f[V]-c\f[R] or \f[V]--create\f[R]) the update (\f[V]-u\f[R] or -\f[V]--update\f[R] ) and the generate-index (\f[V]-i\f[R] or -\f[V]--generate-index=\f[R]\f[I]FILE\f[R]) main operation modes: -.TP -\f[V]-0\f[R] or \f[V]--no-compress\f[R] -Stores without using ZIP compression. -.TP -\f[V]--date=\f[R]\f[I]TIMESTAMP\f[R] -The timestamp in ISO-8601 extended offset date-time with optional -time-zone format, to use for the timestamp of the entries, e.g. -\[dq]2022-02-12T12:30:00-05:00\[dq]. -.SH OPERATION MODIFIERS VALID ONLY IN EXTRACT MODE -.TP -\f[V]--dir\f[R] \f[I]DIR\f[R] -Directory into which the JAR file will be extracted. -.TP -\f[V]-k\f[R] or \f[V]--keep-old-files\f[R] -Do not overwrite existing files. -If a Jar file entry with the same name exists in the target directory, -the existing file will not be overwritten. -As a result, if a file appears more than once in an archive, later -copies will not overwrite earlier copies. -Also note that some file system can be case insensitive. -.SH OTHER OPTIONS -.PP -The following options are recognized by the \f[V]jar\f[R] command and -not used with operation modes: -.TP -\f[V]-h\f[R] or \f[V]--help\f[R][\f[V]:compat\f[R]] -Displays the command-line help for the \f[V]jar\f[R] command or -optionally the compatibility help. -.TP -\f[V]--help-extra\f[R] -Displays help on extra options. -.TP -\f[V]--version\f[R] -Prints the program version. -.SH EXAMPLES OF JAR COMMAND SYNTAX -.IP \[bu] 2 -Create an archive, \f[V]classes.jar\f[R], that contains two class files, -\f[V]Foo.class\f[R] and \f[V]Bar.class\f[R]. -.RS 2 -.RS -.PP -\f[V]jar --create --file classes.jar Foo.class Bar.class\f[R] -.RE -.RE -.IP \[bu] 2 -Create an archive, \f[V]classes.jar\f[R], that contains two class files, -\f[V]Foo.class\f[R] and \f[V]Bar.class\f[R] setting the last modified -date and time to \f[V]2021 Jan 6 12:36:00\f[R]. -.RS 2 -.RS -.PP -\f[V]jar --create --date=\[dq]2021-01-06T14:36:00+02:00\[dq] --file=classes.jar Foo.class Bar.class\f[R] -.RE -.RE -.IP \[bu] 2 -Create an archive, \f[V]classes.jar\f[R], by using an existing manifest, -\f[V]mymanifest\f[R], that contains all of the files in the directory -\f[V]foo/\f[R]. -.RS 2 -.RS -.PP -\f[V]jar --create --file classes.jar --manifest mymanifest -C foo/\f[R] -.RE -.RE -.IP \[bu] 2 -Create a modular JAR archive,\f[V]foo.jar\f[R], where the module -descriptor is located in \f[V]classes/module-info.class\f[R]. -.RS 2 -.RS -.PP -\f[V]jar --create --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/classes resources\f[R] -.RE -.RE -.IP \[bu] 2 -Update an existing non-modular JAR, \f[V]foo.jar\f[R], to a modular JAR -file. -.RS 2 -.RS -.PP -\f[V]jar --update --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/module-info.class\f[R] -.RE -.RE -.IP \[bu] 2 -Create a versioned or multi-release JAR, \f[V]foo.jar\f[R], that places -the files in the \f[V]classes\f[R] directory at the root of the JAR, and -the files in the \f[V]classes-10\f[R] directory in the -\f[V]META-INF/versions/10\f[R] directory of the JAR. -.RS 2 -.PP -In this example, the \f[V]classes/com/foo\f[R] directory contains two -classes, \f[V]com.foo.Hello\f[R] (the entry point class) and -\f[V]com.foo.NameProvider\f[R], both compiled for JDK 8. -The \f[V]classes-10/com/foo\f[R] directory contains a different version -of the \f[V]com.foo.NameProvider\f[R] class, this one containing JDK 10 -specific code and compiled for JDK 10. -.PP -Given this setup, create a multirelease JAR file \f[V]foo.jar\f[R] by -running the following command from the directory containing the -directories \f[V]classes\f[R] and \f[V]classes-10\f[R] . -.RS -.PP -\f[V]jar --create --file foo.jar --main-class com.foo.Hello -C classes . --release 10 -C classes-10 .\f[R] -.RE -.PP -The JAR file \f[V]foo.jar\f[R] now contains: -.IP -.nf -\f[CB] -% jar -tf foo.jar - -META-INF/ -META-INF/MANIFEST.MF -com/ -com/foo/ -com/foo/Hello.class -com/foo/NameProvider.class -META-INF/versions/10/com/ -META-INF/versions/10/com/foo/ -META-INF/versions/10/com/foo/NameProvider.class -\f[R] -.fi -.PP -As well as other information, the file \f[V]META-INF/MANIFEST.MF\f[R], -will contain the following lines to indicate that this is a multirelease -JAR file with an entry point of \f[V]com.foo.Hello\f[R]. -.IP -.nf -\f[CB] -\&... -Main-Class: com.foo.Hello -Multi-Release: true -\f[R] -.fi -.PP -Assuming that the \f[V]com.foo.Hello\f[R] class calls a method on the -\f[V]com.foo.NameProvider\f[R] class, running the program using JDK 10 -will ensure that the \f[V]com.foo.NameProvider\f[R] class is the one in -\f[V]META-INF/versions/10/com/foo/\f[R]. -Running the program using JDK 8 will ensure that the -\f[V]com.foo.NameProvider\f[R] class is the one at the root of the JAR, -in \f[V]com/foo\f[R]. -.RE -.IP \[bu] 2 -Create an archive, \f[V]my.jar\f[R], by reading options and lists of -class files from the file \f[V]classes.list\f[R]. -.RS 2 -.PP -\f[B]Note:\f[R] -.PP -To shorten or simplify the \f[V]jar\f[R] command, you can provide an arg -file that lists the files to include in the JAR file and pass it to the -\f[V]jar\f[R] command with the at sign (\f[V]\[at]\f[R]) as a prefix. -.RS -.PP -\f[V]jar --create --file my.jar \[at]classes.list\f[R] -.RE -.PP -If one or more entries in the arg file cannot be found then the jar -command fails without creating the JAR file. -.RE -.IP \[bu] 2 -Extract the JAR file \f[V]foo.jar\f[R] to \f[V]/tmp/bar/\f[R] directory: -.RS 2 -.RS -.PP -\f[V]jar -xf foo.jar -C /tmp/bar/\f[R] -.RE -.PP -Alternatively, you can also do: -.RS -.PP -\f[V]jar --extract --file foo.jar --dir /tmp/bar/\f[R] -.RE -.RE diff --git a/src/jdk.jartool/share/man/jar.md b/src/jdk.jartool/share/man/jar.md new file mode 100644 index 00000000000..709786fe89b --- /dev/null +++ b/src/jdk.jartool/share/man/jar.md @@ -0,0 +1,313 @@ +--- +# Copyright (c) 1997, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JAR(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jar - create an archive for classes and resources, and manipulate or restore +individual classes or resources from an archive + +## Synopsis + +`jar` \[*OPTION* ...\] \[ \[`--release` *VERSION*\] \[`-C` *dir*\] *files*\] +... + +## Description + +The `jar` command is a general-purpose archiving and compression tool, based on +the ZIP and ZLIB compression formats. Initially, the `jar` command was designed +to package Java applets (not supported since JDK 11) or applications; however, +beginning with JDK 9, users can use the `jar` command to create modular JARs. +For transportation and deployment, it's usually more convenient to package +modules as modular JARs. + +The syntax for the `jar` command resembles the syntax for the `tar` command. It +has several main operation modes, defined by one of the mandatory operation +arguments. Other arguments are either options that modify the behavior of the +operation or are required to perform the operation. + +When modules or the components of an application (files, images and sounds) are +combined into a single archive, they can be downloaded by a Java agent (such as +a browser) in a single HTTP transaction, rather than requiring a new connection +for each piece. This dramatically improves download times. The `jar` command +also compresses files, which further improves download time. The `jar` command +also enables individual entries in a file to be signed so that their origin can +be authenticated. A JAR file can be used as a class path entry, whether or not +it's compressed. + +An archive becomes a modular JAR when you include a module descriptor, +`module-info.class`, in the root of the given directories or in the root of +the `.jar` archive. The following operations described in [Operation Modifiers +Valid Only in Create and Update Modes] are valid only when creating or +updating a modular jar or updating an existing non-modular jar: + +- `--module-version` + +- `--hash-modules` + +- `--module-path` + +**Note:** + +All mandatory or optional arguments for long options are also mandatory or +optional for any corresponding short options. + +## Main Operation Modes + +When using the `jar` command, you must specify the operation for it to perform. +You specify the operation mode for the `jar` command by including the +appropriate operation arguments described in this section. You can mix an +operation argument with other one-letter options. Generally the operation +argument is the first argument specified on the command line. + +`-c` or `--create` +: Creates the archive. + +`-i` *FILE* or `--generate-index=`*FILE* +: Generates index information for the specified JAR file. This option is deprecated + and may be removed in a future release. + +`-t` or `--list` +: Lists the table of contents for the archive. + +`-u` or `--update` +: Updates an existing JAR file. + +`-x` or `--extract` +: Extracts the named (or all) files from the archive. + If a file with the same name appears more than once in + the archive, each copy will be extracted, with later copies + overwriting (replacing) earlier copies unless -k is specified. + +`-d` or `--describe-module` +: Prints the module descriptor or automatic module name. + +## Operation Modifiers Valid in Any Mode + +You can use the following options to customize the actions of any operation +mode included in the `jar` command. + +`-C` *DIR* +: When used with the create operation mode, changes the specified directory + and includes the *files* specified at the end of the command line. + + `jar` \[*OPTION* ...\] \[ \[`--release` *VERSION*\] \[`-C` *dir*\] + *files*\] + + When used with the extract operation mode, specifies the destination directory + where the JAR file will be extracted. Unlike with the create operation mode, + this option can be specified only once with the extract operation mode. + +`-f` *FILE* or `--file=`*FILE* +: Specifies the archive file name. + +`--release` *VERSION* +: Creates a multirelease JAR file. Places all files specified after the + option into a versioned directory of the JAR file named + `META-INF/versions/`*VERSION*`/`, where *VERSION* must be must be a + positive integer whose value is 9 or greater. + + At run time, where more than one version of a class exists in the JAR, the + JDK will use the first one it finds, searching initially in the directory + tree whose *VERSION* number matches the JDK's major version number. It will + then look in directories with successively lower *VERSION* numbers, and + finally look in the root of the JAR. + +`-v` or `--verbose` +: Sends or prints verbose output to standard output. + +## Operation Modifiers Valid Only in Create and Update Modes + +You can use the following options to customize the actions of the create and +the update main operation modes: + +`-e` *CLASSNAME* or `--main-class=`*CLASSNAME* +: Specifies the application entry point for standalone applications bundled + into a modular or executable modular JAR file. + +`-m` *FILE* or `--manifest=`*FILE* +: Includes the manifest information from the given manifest file. + +`-M` or `--no-manifest` +: Doesn't create a manifest file for the entries. + +`--module-version=`*VERSION* +: Specifies the module version, when creating or updating a modular JAR file, + or updating a non-modular JAR file. + +`--hash-modules=`*PATTERN* +: Computes and records the hashes of modules matched by the given pattern and + that depend upon directly or indirectly on a modular JAR file being created + or a non-modular JAR file being updated. + +`-p` or `--module-path` +: Specifies the location of module dependence for generating the hash. + +`@`*file* +: Reads `jar` options and file names from a text file as if they were supplied +on the command line + +## Operation Modifiers Valid Only in Create, Update, and Generate-index Modes + +You can use the following options to customize the actions of the create (`-c` +or `--create`) the update (`-u` or `--update` ) and the generate-index (`-i` or +`--generate-index=`*FILE*) main operation modes: + +`-0` or `--no-compress` +: Stores without using ZIP compression. + +`--date=`*TIMESTAMP* +: The timestamp in ISO-8601 extended offset date-time with optional time-zone + format, to use for the timestamp of the entries, + e.g. "2022-02-12T12:30:00-05:00". + +## Operation Modifiers Valid Only in Extract Mode + +`--dir` *DIR* +: Directory into which the JAR file will be extracted. + +`-k` or `--keep-old-files` +: Do not overwrite existing files. + If a Jar file entry with the same name exists in the target directory, the + existing file will not be overwritten. + As a result, if a file appears more than once in an archive, later copies will not overwrite + earlier copies. + Also note that some file system can be case insensitive. + +## Other Options + +The following options are recognized by the `jar` command and not used with +operation modes: + +`-h` or `--help`\[`:compat`\] +: Displays the command-line help for the `jar` command or optionally the + compatibility help. + +`--help-extra` +: Displays help on extra options. + +`--version` +: Prints the program version. + +## Examples of jar Command Syntax + +- Create an archive, `classes.jar`, that contains two class files, + `Foo.class` and `Bar.class`. + + > `jar --create --file classes.jar Foo.class Bar.class` + +- Create an archive, `classes.jar`, that contains two class files, + `Foo.class` and `Bar.class` setting the last modified date and time to `2021 Jan 6 12:36:00`. + + > `jar --create --date="2021-01-06T14:36:00+02:00" --file=classes.jar Foo.class Bar.class` + +- Create an archive, `classes.jar`, by using an existing manifest, + `mymanifest`, that contains all of the files in the directory `foo/`. + + > `jar --create --file classes.jar --manifest mymanifest -C foo/` + +- Create a modular JAR archive,`foo.jar`, where the module descriptor is + located in `classes/module-info.class`. + + > `jar --create --file foo.jar --main-class com.foo.Main + --module-version 1.0 -C foo/classes resources` + +- Update an existing non-modular JAR, `foo.jar`, to a modular JAR file. + + > `jar --update --file foo.jar --main-class com.foo.Main + --module-version 1.0 -C foo/module-info.class` + +- Create a versioned or multi-release JAR, `foo.jar`, that places the files + in the `classes` directory at the root of the JAR, and the files in the + `classes-10` directory in the `META-INF/versions/10` directory of the JAR. + + In this example, the `classes/com/foo` directory contains two classes, + `com.foo.Hello` (the entry point class) and `com.foo.NameProvider`, both + compiled for JDK 8. The `classes-10/com/foo` directory contains a different + version of the `com.foo.NameProvider` class, this one containing JDK 10 + specific code and compiled for JDK 10. + + Given this setup, create a multirelease JAR file `foo.jar` by running the + following command from the directory containing the directories `classes` + and `classes-10` . + + > `jar --create --file foo.jar --main-class com.foo.Hello -C classes . + --release 10 -C classes-10 .` + + The JAR file `foo.jar` now contains: + + ``` + % jar -tf foo.jar + + META-INF/ + META-INF/MANIFEST.MF + com/ + com/foo/ + com/foo/Hello.class + com/foo/NameProvider.class + META-INF/versions/10/com/ + META-INF/versions/10/com/foo/ + META-INF/versions/10/com/foo/NameProvider.class + ``` + + As well as other information, the file `META-INF/MANIFEST.MF`, will contain + the following lines to indicate that this is a multirelease JAR file with + an entry point of `com.foo.Hello`. + + ``` + ... + Main-Class: com.foo.Hello + Multi-Release: true + ``` + + Assuming that the `com.foo.Hello` class calls a method on the + `com.foo.NameProvider` class, running the program using JDK 10 will ensure + that the `com.foo.NameProvider` class is the one in + `META-INF/versions/10/com/foo/`. Running the program using JDK 8 will + ensure that the `com.foo.NameProvider` class is the one at the root of the + JAR, in `com/foo`. + +- Create an archive, `my.jar`, by reading options and lists of class files + from the file `classes.list`. + + **Note:** + + To shorten or simplify the `jar` command, you can provide an arg file that lists + the files to include in the JAR file and pass it to the `jar` command with the at sign (`@`) + as a prefix. + + > `jar --create --file my.jar @classes.list` + + If one or more entries in the arg file cannot be found then the jar command fails without creating the JAR file. + +- Extract the JAR file `foo.jar` to `/tmp/bar/` directory: + + > `jar -xf foo.jar -C /tmp/bar/` + + Alternatively, you can also do: + + > `jar --extract --file foo.jar --dir /tmp/bar/` diff --git a/src/jdk.jartool/share/man/jarsigner.1 b/src/jdk.jartool/share/man/jarsigner.1 deleted file mode 100644 index d085efcfcd0..00000000000 --- a/src/jdk.jartool/share/man/jarsigner.1 +++ /dev/null @@ -1,1395 +0,0 @@ -.\" Copyright (c) 1998, 2023, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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. -.\" -'\" t -.\" Automatically generated by Pandoc 2.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JARSIGNER" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -jarsigner - sign and verify Java Archive (JAR) files -.SH SYNOPSIS -.PP -\f[V]jarsigner\f[R] [\f[I]options\f[R]] \f[I]jar-file\f[R] -\f[I]alias\f[R] -.PP -\f[V]jarsigner\f[R] \f[V]-verify\f[R] [\f[I]options\f[R]] -\f[I]jar-file\f[R] [\f[I]alias\f[R] ...] -.PP -\f[V]jarsigner\f[R] \f[V]-version\f[R] -.TP -\f[I]options\f[R] -The command-line options. -See \f[B]Options for jarsigner\f[R]. -.TP -\f[V]-verify\f[R] -The \f[V]-verify\f[R] option can take zero or more keystore alias names -after the JAR file name. -When the \f[V]-verify\f[R] option is specified, the \f[V]jarsigner\f[R] -command checks that the certificate used to verify each signed entry in -the JAR file matches one of the keystore aliases. -The aliases are defined in the keystore specified by \f[V]-keystore\f[R] -or the default keystore. -.RS -.PP -If you also specify the \f[V]-strict\f[R] option, and the -\f[V]jarsigner\f[R] command detects severe warnings, the message, -\[dq]jar verified, with signer errors\[dq] is displayed. -.RE -.TP -\f[I]jar-file\f[R] -The JAR file to be signed. -.RS -.PP -If you also specified the \f[V]-strict\f[R] option, and the -\f[V]jarsigner\f[R] command detected severe warnings, the message, -\[dq]jar signed, with signer errors\[dq] is displayed. -.RE -.TP -\f[I]alias\f[R] -The aliases are defined in the keystore specified by \f[V]-keystore\f[R] -or the default keystore. -.TP -\f[V]-version\f[R] -The \f[V]-version\f[R] option prints the program version of -\f[V]jarsigner\f[R]. -.SH DESCRIPTION -.PP -The \f[V]jarsigner\f[R] tool has two purposes: -.IP \[bu] 2 -To sign Java Archive (JAR) files. -.IP \[bu] 2 -To verify the signatures and integrity of signed JAR files. -.PP -The JAR feature enables the packaging of class files, images, sounds, -and other digital data in a single file for faster and easier -distribution. -A tool named \f[V]jar\f[R] enables developers to produce JAR files. -(Technically, any ZIP file can also be considered a JAR file, although -when created by the \f[V]jar\f[R] command or processed by the -\f[V]jarsigner\f[R] command, JAR files also contain a -\f[V]META-INF/MANIFEST.MF\f[R] file.) -.PP -A digital signature is a string of bits that is computed from some data -(the data being signed) and the private key of an entity (a person, -company, and so on). -Similar to a handwritten signature, a digital signature has many useful -characteristics: -.IP \[bu] 2 -Its authenticity can be verified by a computation that uses the public -key corresponding to the private key used to generate the signature. -.IP \[bu] 2 -It can\[aq]t be forged, assuming the private key is kept secret. -.IP \[bu] 2 -It is a function of the data signed and thus can\[aq]t be claimed to be -the signature for other data as well. -.IP \[bu] 2 -The signed data can\[aq]t be changed. -If the data is changed, then the signature can\[aq]t be verified as -authentic. -.PP -To generate an entity\[aq]s signature for a file, the entity must first -have a public/private key pair associated with it and one or more -certificates that authenticate its public key. -A certificate is a digitally signed statement from one entity that says -that the public key of another entity has a particular value. -.PP -The \f[V]jarsigner\f[R] command uses key and certificate information -from a keystore to generate digital signatures for JAR files. -A keystore is a database of private keys and their associated X.509 -certificate chains that authenticate the corresponding public keys. -The \f[V]keytool\f[R] command is used to create and administer -keystores. -.PP -The \f[V]jarsigner\f[R] command uses an entity\[aq]s private key to -generate a signature. -The signed JAR file contains, among other things, a copy of the -certificate from the keystore for the public key corresponding to the -private key used to sign the file. -The \f[V]jarsigner\f[R] command can verify the digital signature of the -signed JAR file using the certificate inside it (in its signature block -file). -.PP -The \f[V]jarsigner\f[R] command can generate signatures that include a -time stamp that enables a systems or deployer to check whether the JAR -file was signed while the signing certificate was still valid. -.PP -In addition, APIs allow applications to obtain the timestamp -information. -.PP -At this time, the \f[V]jarsigner\f[R] command can only sign JAR files -created by the \f[V]jar\f[R] command or zip files. -JAR files are the same as zip files, except they also have a -\f[V]META-INF/MANIFEST.MF\f[R] file. -A \f[V]META-INF/MANIFEST.MF\f[R] file is created when the -\f[V]jarsigner\f[R] command signs a zip file. -.PP -The default \f[V]jarsigner\f[R] command behavior is to sign a JAR or zip -file. -Use the \f[V]-verify\f[R] option to verify a signed JAR file. -.PP -The \f[V]jarsigner\f[R] command also attempts to validate the -signer\[aq]s certificate after signing or verifying. -During validation, it checks the revocation status of each certificate -in the signer\[aq]s certificate chain when the \f[V]-revCheck\f[R] -option is specified. -If there is a validation error or any other problem, the command -generates warning messages. -If you specify the \f[V]-strict\f[R] option, then the command treats -severe warnings as errors. -See \f[B]Errors and Warnings\f[R]. -.SH KEYSTORE ALIASES -.PP -All keystore entities are accessed with unique aliases. -.PP -When you use the \f[V]jarsigner\f[R] command to sign a JAR file, you -must specify the alias for the keystore entry that contains the private -key needed to generate the signature. -If no output file is specified, it overwrites the original JAR file with -the signed JAR file. -.PP -Keystores are protected with a password, so the store password must be -specified. -You are prompted for it when you don\[aq]t specify it on the command -line. -Similarly, private keys are protected in a keystore with a password, so -the private key\[aq]s password must be specified, and you are prompted -for the password when you don\[aq]t specify it on the command line and -it isn\[aq]t the same as the store password. -.SH KEYSTORE LOCATION -.PP -The \f[V]jarsigner\f[R] command has a \f[V]-keystore\f[R] option for -specifying the URL of the keystore to be used. -The keystore is by default stored in a file named \f[V].keystore\f[R] in -the user\[aq]s home directory, as determined by the \f[V]user.home\f[R] -system property. -.PP -\f[B]Linux and macOS:\f[R] \f[V]user.home\f[R] defaults to the -user\[aq]s home directory. -.PP -The input stream from the \f[V]-keystore\f[R] option is passed to the -\f[V]KeyStore.load\f[R] method. -If \f[V]NONE\f[R] is specified as the URL, then a null stream is passed -to the \f[V]KeyStore.load\f[R] method. -\f[V]NONE\f[R] should be specified when the \f[V]KeyStore\f[R] class -isn\[aq]t file based, for example, when it resides on a hardware token -device. -.SH KEYSTORE IMPLEMENTATION -.PP -The \f[V]KeyStore\f[R] class provided in the \f[V]java.security\f[R] -package supplies a number of well-defined interfaces to access and -modify the information in a keystore. -You can have multiple different concrete implementations, where each -implementation is for a particular type of keystore. -.PP -Currently, there are two command-line tools that use keystore -implementations (\f[V]keytool\f[R] and \f[V]jarsigner\f[R]). -.PP -The default keystore implementation is \f[V]PKCS12\f[R]. -This is a cross platform keystore based on the RSA PKCS12 Personal -Information Exchange Syntax Standard. -This standard is primarily meant for storing or transporting a -user\[aq]s private keys, certificates, and miscellaneous secrets. -There is another built-in implementation, provided by Oracle. -It implements the keystore as a file with a proprietary keystore type -(format) named \f[V]JKS\f[R]. -It protects each private key with its individual password, and also -protects the integrity of the entire keystore with a (possibly -different) password. -.PP -Keystore implementations are provider-based, which means the application -interfaces supplied by the \f[V]KeyStore\f[R] class are implemented in -terms of a Service Provider Interface (SPI). -There is a corresponding abstract \f[V]KeystoreSpi\f[R] class, also in -the \f[V]java.security package\f[R], that defines the Service Provider -Interface methods that providers must implement. -The term provider refers to a package or a set of packages that supply a -concrete implementation of a subset of services that can be accessed by -the Java Security API. -To provide a keystore implementation, clients must implement a provider -and supply a \f[V]KeystoreSpi\f[R] subclass implementation, as described -in \f[B]How to Implement a Provider in the Java Cryptography -Architecture\f[R] -[https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase&id=security_guide_implement_provider_jca]. -.PP -Applications can choose different types of keystore implementations from -different providers, with the \f[V]getInstance\f[R] factory method in -the \f[V]KeyStore\f[R] class. -A keystore type defines the storage and data format of the keystore -information and the algorithms used to protect private keys in the -keystore and the integrity of the keystore itself. -Keystore implementations of different types aren\[aq]t compatible. -.PP -The \f[V]jarsigner\f[R] commands can read file-based keystores from any -location that can be specified using a URL. -In addition, these commands can read non-file-based keystores such as -those provided by MSCAPI on Windows and PKCS11 on all platforms. -.PP -For the \f[V]jarsigner\f[R] and \f[V]keytool\f[R] commands, you can -specify a keystore type at the command line with the -\f[V]-storetype\f[R] option. -.PP -If you don\[aq]t explicitly specify a keystore type, then the tools -choose a keystore implementation based on the value of the -\f[V]keystore.type\f[R] property specified in the security properties -file. -The security properties file is called \f[V]java.security\f[R], and it -resides in the JDK security properties directory, -\f[V]java.home/conf/security\f[R]. -.PP -Each tool gets the \f[V]keystore.type\f[R] value and then examines all -the installed providers until it finds one that implements keystores of -that type. -It then uses the keystore implementation from that provider. -.PP -The \f[V]KeyStore\f[R] class defines a static method named -\f[V]getDefaultType\f[R] that lets applications retrieve the value of -the \f[V]keystore.type\f[R] property. -The following line of code creates an instance of the default keystore -type as specified in the \f[V]keystore.type\f[R] property: -.RS -.PP -\f[V]KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());\f[R] -.RE -.PP -The default keystore type is \f[V]pkcs12\f[R], which is a cross platform -keystore based on the RSA PKCS12 Personal Information Exchange Syntax -Standard. -This is specified by the following line in the security properties file: -.RS -.PP -\f[V]keystore.type=pkcs12\f[R] -.RE -.PP -Case doesn\[aq]t matter in keystore type designations. -For example, \f[V]JKS\f[R] is the same as \f[V]jks\f[R]. -.PP -To have the tools utilize a keystore implementation other than the -default, you can change that line to specify a different keystore type. -For example, if you want to use the Oracle\[aq]s \f[V]jks\f[R] keystore -implementation, then change the line to the following: -.RS -.PP -\f[V]keystore.type=jks\f[R] -.RE -.SH SUPPORTED ALGORITHMS -.PP -By default, the \f[V]jarsigner\f[R] command signs a JAR file using one -of the following algorithms and block file extensions depending on the -type and size of the private key: -.PP -Default Signature Algorithms and Block File Extensions -.TS -tab(@); -l l l l. -T{ -keyalg -T}@T{ -key size -T}@T{ -default sigalg -T}@T{ -block file extension -T} -_ -T{ -DSA -T}@T{ -any size -T}@T{ -SHA256withDSA -T}@T{ -\&.DSA -T} -T{ -RSA -T}@T{ -< 624 -T}@T{ -SHA256withRSA -T}@T{ -\&.RSA -T} -T{ -T}@T{ -<= 7680 -T}@T{ -SHA384withRSA -T}@T{ -T} -T{ -T}@T{ -> 7680 -T}@T{ -SHA512withRSA -T}@T{ -T} -T{ -EC -T}@T{ -< 512 -T}@T{ -SHA384withECDSA -T}@T{ -\&.EC -T} -T{ -T}@T{ ->= 512 -T}@T{ -SHA512withECDSA -T}@T{ -T} -T{ -RSASSA-PSS -T}@T{ -< 624 -T}@T{ -RSASSA-PSS (with SHA-256) -T}@T{ -\&.RSA -T} -T{ -T}@T{ -<= 7680 -T}@T{ -RSASSA-PSS (with SHA-384) -T}@T{ -T} -T{ -T}@T{ -> 7680 -T}@T{ -RSASSA-PSS (with SHA-512) -T}@T{ -T} -T{ -EdDSA -T}@T{ -255 -T}@T{ -Ed25519 -T}@T{ -\&.EC -T} -T{ -T}@T{ -448 -T}@T{ -Ed448 -T}@T{ -T} -.TE -.IP \[bu] 2 -If an RSASSA-PSS key is encoded with parameters, then jarsigner will use -the same parameters in the signature. -Otherwise, jarsigner will use parameters that are determined by the size -of the key as specified in the table above. -For example, an 3072-bit RSASSA-PSS key will use RSASSA-PSS as the -signature algorithm and SHA-384 as the hash and MGF1 algorithms. -.IP \[bu] 2 -If a key algorithm is not listed in this table, the \f[V].DSA\f[R] -extension is used when signing a JAR file. -.PP -These default signature algorithms can be overridden by using the -\f[V]-sigalg\f[R] option. -.PP -The \f[V]jarsigner\f[R] command uses the -\f[V]jdk.jar.disabledAlgorithms\f[R] and -\f[V]jdk.security.legacyAlgorithms\f[R] security properties to determine -which algorithms are considered a security risk. -If the JAR file was signed with any algorithms that are disabled, it -will be treated as an unsigned JAR file. -If the JAR file was signed with any legacy algorithms, it will be -treated as signed with an informational warning to inform users that the -legacy algorithm will be disabled in a future update. -For detailed verification output, include -\f[V]-J-Djava.security.debug=jar\f[R]. -The \f[V]jdk.jar.disabledAlgorithms\f[R] and -\f[V]jdk.security.legacyAlgorithms\f[R] security properties are defined -in the \f[V]java.security\f[R] file (located in the JDK\[aq]s -\f[V]$JAVA_HOME/conf/security\f[R] directory). -.PP -\f[B]Note:\f[R] -.PP -In order to improve out of the box security, default key size and -signature algorithm names are periodically updated to stronger values -with each release of the JDK. -If interoperability with older releases of the JDK is important, please -make sure the defaults are supported by those releases, or alternatively -use the \f[V]-sigalg\f[R] option to override the default values at your -own risk. -.SH THE SIGNED JAR FILE -.PP -When the \f[V]jarsigner\f[R] command is used to sign a JAR file, the -output signed JAR file is exactly the same as the input JAR file, except -that it has two additional files placed in the META-INF directory: -.IP \[bu] 2 -A signature file with an \f[V].SF\f[R] extension -.IP \[bu] 2 -A signature block file with a \f[V].DSA\f[R], \f[V].RSA\f[R], or -\f[V].EC\f[R] extension -.PP -The base file names for these two files come from the value of the -\f[V]-sigfile\f[R] option. -For example, when the option is \f[V]-sigfile MKSIGN\f[R], the files are -named \f[V]MKSIGN.SF\f[R] and \f[V]MKSIGN.RSA\f[R]. -In this document, we assume the signer always uses an RSA key. -.PP -If no \f[V]-sigfile\f[R] option appears on the command line, then the -base file name for the \f[V].SF\f[R] and the signature block files is -the first 8 characters of the alias name specified on the command line, -all converted to uppercase. -If the alias name has fewer than 8 characters, then the full alias name -is used. -If the alias name contains any characters that aren\[aq]t allowed in a -signature file name, then each such character is converted to an -underscore (_) character in forming the file name. -Valid characters include letters, digits, underscores, and hyphens. -.SH SIGNATURE FILE -.PP -A signature file (\f[V].SF\f[R] file) looks similar to the manifest file -that is always included in a JAR file when the \f[V]jarsigner\f[R] -command is used to sign the file. -For each source file included in the JAR file, the \f[V].SF\f[R] file -has two lines, such as in the manifest file, that list the following: -.IP \[bu] 2 -File name -.IP \[bu] 2 -Name of the digest algorithm (SHA) -.IP \[bu] 2 -SHA digest value -.PP -\f[B]Note:\f[R] -.PP -The name of the digest algorithm (SHA) and the SHA digest value are on -the same line. -.PP -In the manifest file, the SHA digest value for each source file is the -digest (hash) of the binary data in the source file. -In the \f[V].SF\f[R] file, the digest value for a specified source file -is the hash of the two lines in the manifest file for the source file. -.PP -The signature file, by default, includes a header with a hash of the -whole manifest file. -The header also contains a hash of the manifest header. -The presence of the header enables verification optimization. -See \f[B]JAR File Verification\f[R]. -.SH SIGNATURE BLOCK FILE -.PP -The \f[V].SF\f[R] file is signed and the signature is placed in the -signature block file. -This file also contains, encoded inside it, the certificate or -certificate chain from the keystore that authenticates the public key -corresponding to the private key used for signing. -The file has the extension \f[V].DSA\f[R], \f[V].RSA\f[R], or -\f[V].EC\f[R], depending on the key algorithm used. -See the table in \f[B]Supported Algorithms\f[R]. -.SH SIGNATURE TIME STAMP -.PP -The \f[V]jarsigner\f[R] command used with the following options -generates and stores a signature time stamp when signing a JAR file: -.IP \[bu] 2 -\f[V]-tsa\f[R] \f[I]url\f[R] -.IP \[bu] 2 -\f[V]-tsacert\f[R] \f[I]alias\f[R] -.IP \[bu] 2 -\f[V]-tsapolicyid\f[R] \f[I]policyid\f[R] -.IP \[bu] 2 -\f[V]-tsadigestalg\f[R] \f[I]algorithm\f[R] -.PP -See \f[B]Options for jarsigner\f[R]. -.SH JAR FILE VERIFICATION -.PP -A successful JAR file verification occurs when the signatures are valid, -and none of the files that were in the JAR file when the signatures were -generated have changed since then. -JAR file verification involves the following steps: -.IP "1." 3 -Verify the signature of the \f[V].SF\f[R] file. -.RS 4 -.PP -The verification ensures that the signature stored in each signature -block file was generated using the private key corresponding to the -public key whose certificate (or certificate chain) also appears in the -signature block file. -It also ensures that the signature is a valid signature of the -corresponding signature (\f[V].SF\f[R]) file, and thus the \f[V].SF\f[R] -file wasn\[aq]t tampered with. -.RE -.IP "2." 3 -Verify the digest listed in each entry in the \f[V].SF\f[R] file with -each corresponding section in the manifest. -.RS 4 -.PP -The \f[V].SF\f[R] file by default includes a header that contains a hash -of the entire manifest file. -When the header is present, the verification can check to see whether or -not the hash in the header matches the hash of the manifest file. -If there is a match, then verification proceeds to the next step. -.PP -If there is no match, then a less optimized verification is required to -ensure that the hash in each source file information section in the -\f[V].SF\f[R] file equals the hash of its corresponding section in the -manifest file. -See Signature File. -.PP -One reason the hash of the manifest file that is stored in the -\f[V].SF\f[R] file header might not equal the hash of the current -manifest file is that it might contain sections for newly added files -after the file was signed. -For example, suppose one or more files were added to the signed JAR file -(using the \f[V]jar\f[R] tool) that already contains a signature and a -\f[V].SF\f[R] file. -If the JAR file is signed again by a different signer, then the manifest -file is changed (sections are added to it for the new files by the -\f[V]jarsigner\f[R] tool) and a new \f[V].SF\f[R] file is created, but -the original \f[V].SF\f[R] file is unchanged. -A verification is still considered successful if none of the files that -were in the JAR file when the original signature was generated have been -changed since then. -This is because the hashes in the non-header sections of the -\f[V].SF\f[R] file equal the hashes of the corresponding sections in the -manifest file. -.RE -.IP "3." 3 -Read each file in the JAR file that has an entry in the \f[V].SF\f[R] -file. -While reading, compute the file\[aq]s digest and compare the result with -the digest for this file in the manifest section. -The digests should be the same or verification fails. -.RS 4 -.PP -If any serious verification failures occur during the verification -process, then the process is stopped and a security exception is thrown. -The \f[V]jarsigner\f[R] command catches and displays the exception. -.RE -.IP "4." 3 -Check for disabled algorithm usage. -See \f[B]Supported Algorithms\f[R]. -.PP -\f[B]Note:\f[R] -.PP -You should read any addition warnings (or errors if you specified the -\f[V]-strict\f[R] option), as well as the content of the certificate (by -specifying the \f[V]-verbose\f[R] and \f[V]-certs\f[R] options) to -determine if the signature can be trusted. -.SH MULTIPLE SIGNATURES FOR A JAR FILE -.PP -A JAR file can be signed by multiple people by running the -\f[V]jarsigner\f[R] command on the file multiple times and specifying -the alias for a different person each time, as follows: -.IP -.nf -\f[CB] -jarsigner myBundle.jar susan -jarsigner myBundle.jar kevin -\f[R] -.fi -.PP -When a JAR file is signed multiple times, there are multiple -\f[V].SF\f[R] and signature block files in the resulting JAR file, one -pair for each signature. -In the previous example, the output JAR file includes files with the -following names: -.IP -.nf -\f[CB] -SUSAN.SF -SUSAN.RSA -KEVIN.SF -KEVIN.RSA -\f[R] -.fi -.SH OPTIONS FOR JARSIGNER -.PP -The following sections describe the options for the \f[V]jarsigner\f[R]. -Be aware of the following standards: -.IP \[bu] 2 -All option names are preceded by a hyphen sign (-). -.IP \[bu] 2 -The options can be provided in any order. -.IP \[bu] 2 -Items that are in italics or underlined (option values) represent the -actual values that must be supplied. -.IP \[bu] 2 -The \f[V]-storepass\f[R], \f[V]-keypass\f[R], \f[V]-sigfile\f[R], -\f[V]-sigalg\f[R], \f[V]-digestalg\f[R], \f[V]-signedjar\f[R], and -TSA-related options are only relevant when signing a JAR file; they -aren\[aq]t relevant when verifying a signed JAR file. -The \f[V]-keystore\f[R] option is relevant for signing and verifying a -JAR file. -In addition, aliases are specified when signing and verifying a JAR -file. -.TP -\f[V]-keystore\f[R] \f[I]url\f[R] -Specifies the URL that tells the keystore location. -This defaults to the file \f[V].keystore\f[R] in the user\[aq]s home -directory, as determined by the \f[V]user.home\f[R] system property. -.RS -.PP -A keystore is required when signing. -You must explicitly specify a keystore when the default keystore -doesn\[aq]t exist or if you want to use one other than the default. -.PP -A keystore isn\[aq]t required when verifying, but if one is specified or -the default exists and the \f[V]-verbose\f[R] option was also specified, -then additional information is output regarding whether or not any of -the certificates used to verify the JAR file are contained in that -keystore. -.PP -The \f[V]-keystore\f[R] argument can be a file name and path -specification rather than a URL, in which case it is treated the same as -a file: URL, for example, the following are equivalent: -.IP \[bu] 2 -\f[V]-keystore\f[R] \f[I]filePathAndName\f[R] -.IP \[bu] 2 -\f[V]-keystore file:\f[R]\f[I]filePathAndName\f[R] -.PP -If the Sun PKCS #11 provider was configured in the -\f[V]java.security\f[R] security properties file (located in the -JDK\[aq]s \f[V]$JAVA_HOME/conf/security\f[R] directory), then the -\f[V]keytool\f[R] and \f[V]jarsigner\f[R] tools can operate on the PKCS -#11 token by specifying these options: -.RS -.PP -\f[V]-keystore NONE -storetype PKCS11\f[R] -.RE -.PP -For example, the following command lists the contents of the configured -PKCS#11 token: -.RS -.PP -\f[V]keytool -keystore NONE -storetype PKCS11 -list\f[R] -.RE -.RE -.TP -\f[V]-storepass\f[R] [\f[V]:env\f[R] | \f[V]:file\f[R]] \f[I]argument\f[R] -Specifies the password that is required to access the keystore. -This is only needed when signing (not verifying) a JAR file. -In that case, if a \f[V]-storepass\f[R] option isn\[aq]t provided at the -command line, then the user is prompted for the password. -.RS -.PP -If the modifier \f[V]env\f[R] or \f[V]file\f[R] isn\[aq]t specified, -then the password has the value \f[V]argument\f[R]. -Otherwise, the password is retrieved as follows: -.IP \[bu] 2 -\f[V]env\f[R]: Retrieve the password from the environment variable named -\f[I]argument\f[R]. -.IP \[bu] 2 -\f[V]file\f[R]: Retrieve the password from the file named -\f[I]argument\f[R]. -.PP -\f[B]Note:\f[R] -.PP -The password shouldn\[aq]t be specified on the command line or in a -script unless it is for testing purposes, or you are on a secure system. -.RE -.TP -\f[V]-storetype\f[R] \f[I]storetype\f[R] -Specifies the type of keystore to be instantiated. -The default keystore type is the one that is specified as the value of -the \f[V]keystore.type\f[R] property in the security properties file, -which is returned by the static \f[V]getDefaultType\f[R] method in -\f[V]java.security.KeyStore\f[R]. -.RS -.PP -The PIN for a PKCS #11 token can also be specified with the -\f[V]-storepass\f[R] option. -If none is specified, then the \f[V]keytool\f[R] and \f[V]jarsigner\f[R] -commands prompt for the token PIN. -If the token has a protected authentication path (such as a dedicated -PIN-pad or a biometric reader), then the \f[V]-protected\f[R] option -must be specified and no password options can be specified. -.RE -.TP -\f[V]-keypass\f[R] [\f[V]:env\f[R] | \f[V]:file\f[R]] \f[I]argument\f[R] \f[V]-certchain\f[R] \f[I]file\f[R] -Specifies the password used to protect the private key of the keystore -entry addressed by the alias specified on the command line. -The password is required when using \f[V]jarsigner\f[R] to sign a JAR -file. -If no password is provided on the command line, and the required -password is different from the store password, then the user is prompted -for it. -.RS -.PP -If the modifier \f[V]env\f[R] or \f[V]file\f[R] isn\[aq]t specified, -then the password has the value \f[V]argument\f[R]. -Otherwise, the password is retrieved as follows: -.IP \[bu] 2 -\f[V]env\f[R]: Retrieve the password from the environment variable named -\f[I]argument\f[R]. -.IP \[bu] 2 -\f[V]file\f[R]: Retrieve the password from the file named -\f[I]argument\f[R]. -.PP -\f[B]Note:\f[R] -.PP -The password shouldn\[aq]t be specified on the command line or in a -script unless it is for testing purposes, or you are on a secure system. -.RE -.TP -\f[V]-certchain\f[R] \f[I]file\f[R] -Specifies the certificate chain to be used when the certificate chain -associated with the private key of the keystore entry that is addressed -by the alias specified on the command line isn\[aq]t complete. -This can happen when the keystore is located on a hardware token where -there isn\[aq]t enough capacity to hold a complete certificate chain. -The file can be a sequence of concatenated X.509 certificates, or a -single PKCS#7 formatted data block, either in binary encoding format or -in printable encoding format (also known as Base64 encoding) as defined -by \f[B]Internet RFC 1421 Certificate Encoding Standard\f[R] -[http://tools.ietf.org/html/rfc1421]. -.TP -\f[V]-sigfile\f[R] \f[I]file\f[R] -Specifies the base file name to be used for the generated \f[V].SF\f[R] -and signature block files. -For example, if file is \f[V]DUKESIGN\f[R], then the generated -\f[V].SF\f[R] and signature block files are named \f[V]DUKESIGN.SF\f[R] -and \f[V]DUKESIGN.RSA\f[R], and placed in the \f[V]META-INF\f[R] -directory of the signed JAR file. -.RS -.PP -The characters in the file must come from the set \f[V]a-zA-Z0-9_-\f[R]. -Only letters, numbers, underscore, and hyphen characters are allowed. -All lowercase characters are converted to uppercase for the -\f[V].SF\f[R] and signature block file names. -.PP -If no \f[V]-sigfile\f[R] option appears on the command line, then the -base file name for the \f[V].SF\f[R] and signature block files is the -first 8 characters of the alias name specified on the command line, all -converted to upper case. -If the alias name has fewer than 8 characters, then the full alias name -is used. -If the alias name contains any characters that aren\[aq]t valid in a -signature file name, then each such character is converted to an -underscore (_) character to form the file name. -.RE -.TP -\f[V]-signedjar\f[R] \f[I]file\f[R] -Specifies the name of signed JAR file. -.TP -\f[V]-digestalg\f[R] \f[I]algorithm\f[R] -Specifies the name of the message digest algorithm to use when digesting -the entries of a JAR file. -.RS -.PP -For a list of standard message digest algorithm names, see the Java -Security Standard Algorithm Names Specification. -.PP -If this option isn\[aq]t specified, then \f[V]SHA-384\f[R] is used. -There must either be a statically installed provider supplying an -implementation of the specified algorithm or the user must specify one -with the \f[V]-addprovider\f[R] or \f[V]-providerClass\f[R] options; -otherwise, the command will not succeed. -.RE -.TP -\f[V]-sigalg\f[R] \f[I]algorithm\f[R] -Specifies the name of the signature algorithm to use to sign the JAR -file. -.RS -.PP -This algorithm must be compatible with the private key used to sign the -JAR file. -If this option isn\[aq]t specified, then use a default algorithm -matching the private key as described in the \f[B]Supported -Algorithms\f[R] section. -There must either be a statically installed provider supplying an -implementation of the specified algorithm or you must specify one with -the \f[V]-addprovider\f[R] or \f[V]-providerClass\f[R] option; -otherwise, the command doesn\[aq]t succeed. -.PP -For a list of standard signature algorithm names, see the Java Security -Standard Algorithm Names Specification. -.RE -.TP -\f[V]-verify\f[R] -Verifies a signed JAR file. -.TP -\f[V]-verbose\f[R][\f[V]:\f[R]\f[I]suboptions\f[R]] -When the \f[V]-verbose\f[R] option appears on the command line, it -indicates that the \f[V]jarsigner\f[R] use the verbose mode when signing -or verifying with the suboptions determining how much information is -shown. -This causes the , which causes \f[V]jarsigner\f[R] to output extra -information about the progress of the JAR signing or verification. -The \f[I]suboptions\f[R] can be \f[V]all\f[R], \f[V]grouped\f[R], or -\f[V]summary\f[R]. -.RS -.PP -If the \f[V]-certs\f[R] option is also specified, then the default mode -(or suboption \f[V]all\f[R]) displays each entry as it is being -processed, and after that, the certificate information for each signer -of the JAR file. -.PP -If the \f[V]-certs\f[R] and the \f[V]-verbose:grouped\f[R] suboptions -are specified, then entries with the same signer info are grouped and -displayed together with their certificate information. -.PP -If \f[V]-certs\f[R] and the \f[V]-verbose:summary\f[R] suboptions are -specified, then entries with the same signer information are grouped and -displayed together with their certificate information. -.PP -Details about each entry are summarized and displayed as \f[I]one entry -(and more)\f[R]. -See \f[B]Example of Verifying a Signed JAR File\f[R] and \f[B]Example of -Verification with Certificate Information\f[R]. -.RE -.TP -\f[V]-certs\f[R] -If the \f[V]-certs\f[R] option appears on the command line with the -\f[V]-verify\f[R] and \f[V]-verbose\f[R] options, then the output -includes certificate information for each signer of the JAR file. -This information includes the name of the type of certificate (stored in -the signature block file) that certifies the signer\[aq]s public key, -and if the certificate is an X.509 certificate (an instance of the -\f[V]java.security.cert.X509Certificate\f[R]), then the distinguished -name of the signer. -.RS -.PP -The keystore is also examined. -If no keystore value is specified on the command line, then the default -keystore file (if any) is checked. -If the public key certificate for a signer matches an entry in the -keystore, then the alias name for the keystore entry for that signer is -displayed in parentheses. -.RE -.TP -\f[V]-revCheck\f[R] -This option enables revocation checking of certificates when signing or -verifying a JAR file. -The \f[V]jarsigner\f[R] command attempts to make network connections to -fetch OCSP responses and CRLs if the \f[V]-revCheck\f[R] option is -specified on the command line. -Note that revocation checks are not enabled unless this option is -specified. -.TP -\f[V]-tsa\f[R] \f[I]url\f[R] -If \f[V]-tsa http://example.tsa.url\f[R] appears on the command line -when signing a JAR file then a time stamp is generated for the -signature. -The URL, \f[V]http://example.tsa.url\f[R], identifies the location of -the Time Stamping Authority (TSA) and overrides any URL found with the -\f[V]-tsacert\f[R] option. -The \f[V]-tsa\f[R] option doesn\[aq]t require the TSA public key -certificate to be present in the keystore. -.RS -.PP -To generate the time stamp, \f[V]jarsigner\f[R] communicates with the -TSA with the Time-Stamp Protocol (TSP) defined in RFC 3161. -When successful, the time stamp token returned by the TSA is stored with -the signature in the signature block file. -.RE -.TP -\f[V]-tsacert\f[R] \f[I]alias\f[R] -When \f[V]-tsacert\f[R] \f[I]alias\f[R] appears on the command line when -signing a JAR file, a time stamp is generated for the signature. -The alias identifies the TSA public key certificate in the keystore that -is in effect. -The entry\[aq]s certificate is examined for a Subject Information Access -extension that contains a URL identifying the location of the TSA. -.RS -.PP -The TSA public key certificate must be present in the keystore when -using the \f[V]-tsacert\f[R] option. -.RE -.TP -\f[V]-tsapolicyid\f[R] \f[I]policyid\f[R] -Specifies the object identifier (OID) that identifies the policy ID to -be sent to the TSA server. -If this option isn\[aq]t specified, no policy ID is sent and the TSA -server will choose a default policy ID. -.RS -.PP -Object identifiers are defined by X.696, which is an ITU -Telecommunication Standardization Sector (ITU-T) standard. -These identifiers are typically period-separated sets of non-negative -digits like \f[V]1.2.3.4\f[R], for example. -.RE -.TP -\f[V]-tsadigestalg\f[R] \f[I]algorithm\f[R] -Specifies the message digest algorithm that is used to generate the -message imprint to be sent to the TSA server. -If this option isn\[aq]t specified, SHA-384 will be used. -.RS -.PP -See \f[B]Supported Algorithms\f[R]. -.PP -For a list of standard message digest algorithm names, see the Java -Security Standard Algorithm Names Specification. -.RE -.TP -\f[V]-internalsf\f[R] -In the past, the signature block file generated when a JAR file was -signed included a complete encoded copy of the \f[V].SF\f[R] file -(signature file) also generated. -This behavior has been changed. -To reduce the overall size of the output JAR file, the signature block -file by default doesn\[aq]t contain a copy of the \f[V].SF\f[R] file -anymore. -If \f[V]-internalsf\f[R] appears on the command line, then the old -behavior is utilized. -This option is useful for testing. -In practice, don\[aq]t use the \f[V]-internalsf\f[R] option because it -incurs higher overhead. -.TP -\f[V]-sectionsonly\f[R] -If the \f[V]-sectionsonly\f[R] option appears on the command line, then -the \f[V].SF\f[R] file (signature file) generated when a JAR file is -signed doesn\[aq]t include a header that contains a hash of the whole -manifest file. -It contains only the information and hashes related to each individual -source file included in the JAR file. -See Signature File. -.RS -.PP -By default, this header is added, as an optimization. -When the header is present, whenever the JAR file is verified, the -verification can first check to see whether the hash in the header -matches the hash of the whole manifest file. -When there is a match, verification proceeds to the next step. -When there is no match, it is necessary to do a less optimized -verification that the hash in each source file information section in -the \f[V].SF\f[R] file equals the hash of its corresponding section in -the manifest file. -See \f[B]JAR File Verification\f[R]. -.PP -The \f[V]-sectionsonly\f[R] option is primarily used for testing. -It shouldn\[aq]t be used other than for testing because using it incurs -higher overhead. -.RE -.TP -\f[V]-protected\f[R] -Values can be either \f[V]true\f[R] or \f[V]false\f[R]. -Specify \f[V]true\f[R] when a password must be specified through a -protected authentication path such as a dedicated PIN reader. -.TP -\f[V]-providerName\f[R] \f[I]providerName\f[R] -If more than one provider was configured in the \f[V]java.security\f[R] -security properties file, then you can use the \f[V]-providerName\f[R] -option to target a specific provider instance. -The argument to this option is the name of the provider. -.RS -.PP -For the Oracle PKCS #11 provider, \f[I]providerName\f[R] is of the form -\f[V]SunPKCS11-\f[R]\f[I]TokenName\f[R], where \f[I]TokenName\f[R] is -the name suffix that the provider instance has been configured with, as -detailed in the configuration attributes table. -For example, the following command lists the contents of the -\f[V]PKCS #11\f[R] keystore provider instance with name suffix -\f[V]SmartCard\f[R]: -.RS -.PP -\f[V]jarsigner -keystore NONE -storetype PKCS11 -providerName SunPKCS11-SmartCard -list\f[R] -.RE -.RE -.TP -\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerArg\f[R] \f[I]arg\f[R]] -Adds a security provider by name (such as SunPKCS11) and an optional -configure argument. -The value of the security provider is the name of a security provider -that is defined in a module. -.RS -.PP -Used with the \f[V]-providerArg ConfigFilePath\f[R] option, the -\f[V]keytool\f[R] and \f[V]jarsigner\f[R] tools install the provider -dynamically and use \f[V]ConfigFilePath\f[R] for the path to the token -configuration file. -The following example shows a command to list a \f[V]PKCS #11\f[R] -keystore when the Oracle PKCS #11 provider wasn\[aq]t configured in the -security properties file. -.RS -.PP -\f[V]jarsigner -keystore NONE -storetype PKCS11 -addprovider SunPKCS11 -providerArg /mydir1/mydir2/token.config\f[R] -.RE -.RE -.TP -\f[V]-providerClass\f[R] \f[I]provider-class-name\f[R] [\f[V]-providerArg\f[R] \f[I]arg\f[R]] -Used to specify the name of cryptographic service provider\[aq]s master -class file when the service provider isn\[aq]t listed in the -\f[V]java.security\f[R] security properties file. -Adds a security provider by fully-qualified class name and an optional -configure argument. -.RS -.PP -\f[B]Note:\f[R] -.PP -The preferred way to load PKCS11 is by using modules. -See \f[V]-addprovider\f[R]. -.RE -.TP -\f[V]-providerPath\f[R] \f[I]classpath\f[R] -Used to specify the classpath for providers specified by the -\f[V]-providerClass\f[R] option. -Multiple paths should be separated by the system-dependent -path-separator character. -.TP -\f[V]-J\f[R]\f[I]javaoption\f[R] -Passes through the specified \f[I]javaoption\f[R] string directly to the -Java interpreter. -The \f[V]jarsigner\f[R] command is a wrapper around the interpreter. -This option shouldn\[aq]t contain any spaces. -It is useful for adjusting the execution environment or memory usage. -For a list of possible interpreter options, type \f[V]java -h\f[R] or -\f[V]java -X\f[R] at the command line. -.TP -\f[V]-strict\f[R] -During the signing or verifying process, the command may issue warning -messages. -If you specify this option, the exit code of the tool reflects the -severe warning messages that this command found. -See \f[B]Errors and Warnings\f[R]. -.TP -\f[V]-conf\f[R] \f[I]url\f[R] -Specifies a pre-configured options file. -Read the \f[B]keytool documentation\f[R] for details. -The property keys supported are \[dq]jarsigner.all\[dq] for all actions, -\[dq]jarsigner.sign\[dq] for signing, and \[dq]jarsigner.verify\[dq] for -verification. -\f[V]jarsigner\f[R] arguments including the JAR file name and alias -name(s) cannot be set in this file. -.TP -\f[V]-version\f[R] -Prints the program version. -.SH ERRORS AND WARNINGS -.PP -During the signing or verifying process, the \f[V]jarsigner\f[R] command -may issue various errors or warnings. -.PP -If there is a failure, the \f[V]jarsigner\f[R] command exits with code -1. -If there is no failure, but there are one or more severe warnings, the -\f[V]jarsigner\f[R] command exits with code 0 when the \f[V]-strict\f[R] -option is \f[B]not\f[R] specified, or exits with the OR-value of the -warning codes when the \f[V]-strict\f[R] is specified. -If there is only informational warnings or no warning at all, the -command always exits with code 0. -.PP -For example, if a certificate used to sign an entry is expired and has a -KeyUsage extension that doesn\[aq]t allow it to sign a file, the -\f[V]jarsigner\f[R] command exits with code 12 (=4+8) when the -\f[V]-strict\f[R] option is specified. -.PP -\f[B]Note:\f[R] Exit codes are reused because only the values from 0 to -255 are legal on Linux and macOS. -.PP -The following sections describes the names, codes, and descriptions of -the errors and warnings that the \f[V]jarsigner\f[R] command can issue. -.SH FAILURE -.PP -Reasons why the \f[V]jarsigner\f[R] command fails include (but -aren\[aq]t limited to) a command line parsing error, the inability to -find a keypair to sign the JAR file, or the verification of a signed JAR -fails. -.TP -failure -Code 1. -The signing or verifying fails. -.SH SEVERE WARNINGS -.PP -\f[B]Note:\f[R] -.PP -Severe warnings are reported as errors if you specify the -\f[V]-strict\f[R] option. -.PP -Reasons why the \f[V]jarsigner\f[R] command issues a severe warning -include the certificate used to sign the JAR file has an error or the -signed JAR file has other problems. -.TP -hasExpiredCert -Code 4. -This JAR contains entries whose signer certificate has expired. -.TP -hasExpiredTsaCert -Code 4. -The timestamp has expired. -.TP -notYetValidCert -Code 4. -This JAR contains entries whose signer certificate isn\[aq]t yet valid. -.TP -chainNotValidated -Code 4. -This JAR contains entries whose certificate chain isn\[aq]t validated. -.TP -tsaChainNotValidated -Code 64. -The timestamp is invalid. -.TP -signerSelfSigned -Code 4. -This JAR contains entries whose signer certificate is self signed. -.TP -disabledAlg -Code 4. -An algorithm used is considered a security risk and is disabled. -.TP -badKeyUsage -Code 8. -This JAR contains entries whose signer certificate\[aq]s KeyUsage -extension doesn\[aq]t allow code signing. -.TP -badExtendedKeyUsage -Code 8. -This JAR contains entries whose signer certificate\[aq]s -ExtendedKeyUsage extension doesn\[aq]t allow code signing. -.TP -badNetscapeCertType -Code 8. -This JAR contains entries whose signer certificate\[aq]s -NetscapeCertType extension doesn\[aq]t allow code signing. -.TP -hasUnsignedEntry -Code 16. -This JAR contains unsigned entries which haven\[aq]t been -integrity-checked. -.TP -notSignedByAlias -Code 32. -This JAR contains signed entries which aren\[aq]t signed by the -specified alias(es). -.TP -aliasNotInStore -Code 32. -This JAR contains signed entries that aren\[aq]t signed by alias in this -keystore. -.TP -tsaChainNotValidated -Code 64. -This JAR contains entries whose TSA certificate chain is invalid. -.SH INFORMATIONAL WARNINGS -.PP -Informational warnings include those that aren\[aq]t errors but regarded -as bad practice. -They don\[aq]t have a code. -.TP -extraAttributesDetected -The POSIX file permissions and/or symlink attributes are detected during -signing or verifying a JAR file. -The \f[V]jarsigner\f[R] tool preserves these attributes in the newly -signed file but warns that these attributes are unsigned and not -protected by the signature. -.TP -hasExpiringCert -This JAR contains entries whose signer certificate expires within six -months. -.TP -hasExpiringTsaCert -The timestamp will expire within one year on \f[V]YYYY-MM-DD\f[R]. -.TP -legacyAlg -An algorithm used is considered a security risk but not disabled. -.TP -noTimestamp -This JAR contains signatures that doesn\[aq]t include a timestamp. -Without a timestamp, users may not be able to validate this JAR file -after the signer certificate\[aq]s expiration date -(\f[V]YYYY-MM-DD\f[R]) or after any future revocation date. -.SH EXAMPLE OF SIGNING A JAR FILE -.PP -Use the following command to sign \f[V]bundle.jar\f[R] with the private -key of a user whose keystore alias is \f[V]jane\f[R] in a keystore named -\f[V]mystore\f[R] in the \f[V]working\f[R] directory and name the signed -JAR file \f[V]sbundle.jar\f[R]: -.RS -.PP -\f[V]jarsigner -keystore /working/mystore -storepass\f[R] -\f[I]keystore_password\f[R] \f[V]-keypass\f[R] -\f[I]private_key_password\f[R] -\f[V]-signedjar sbundle.jar bundle.jar jane\f[R] -.RE -.PP -There is no \f[V]-sigfile\f[R] specified in the previous command so the -generated \f[V].SF\f[R] and signature block files to be placed in the -signed JAR file have default names based on the alias name. -They are named \f[V]JANE.SF\f[R] and \f[V]JANE.RSA\f[R]. -.PP -If you want to be prompted for the store password and the private key -password, then you could shorten the previous command to the following: -.RS -.PP -\f[V]jarsigner -keystore /working/mystore -signedjar sbundle.jar bundle.jar jane\f[R] -.RE -.PP -If the \f[V]keystore\f[R] is the default \f[V]keystore\f[R] -(\f[V].keystore\f[R] in your home directory), then you don\[aq]t need to -specify a \f[V]keystore\f[R], as follows: -.RS -.PP -\f[V]jarsigner -signedjar sbundle.jar bundle.jar jane\f[R] -.RE -.PP -If you want the signed JAR file to overwrite the input JAR file -(\f[V]bundle.jar\f[R]), then you don\[aq]t need to specify a -\f[V]-signedjar\f[R] option, as follows: -.RS -.PP -\f[V]jarsigner bundle.jar jane\f[R] -.RE -.SH EXAMPLE OF VERIFYING A SIGNED JAR FILE -.PP -To verify a signed JAR file to ensure that the signature is valid and -the JAR file wasn\[aq]t been tampered with, use a command such as the -following: -.RS -.PP -\f[V]jarsigner -verify ButtonDemo.jar\f[R] -.RE -.PP -When the verification is successful, \f[V]jar verified\f[R] is -displayed. -Otherwise, an error message is displayed. -You can get more information when you use the \f[V]-verbose\f[R] option. -A sample use of \f[V]jarsigner\f[R] with the \f[V]-verbose\f[R] option -follows: -.IP -.nf -\f[CB] -jarsigner -verify -verbose ButtonDemo.jar - -s 866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF - 825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF - 7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA - 0 Tue Sep 12 20:07:54 EDT 2017 META-INF/ - 0 Tue Sep 12 20:07:16 EDT 2017 components/ - 0 Tue Sep 12 20:07:16 EDT 2017 components/images/ -sm 523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class -sm 3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class -sm 2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp -sm 172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif -sm 235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif -sm 172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif - - s = signature was verified - m = entry is listed in manifest - k = at least one certificate was found in keystore - -- Signed by \[dq]CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US\[dq] - Digest algorithm: SHA-256 - Signature algorithm: SHA256withRSA, 2048-bit key - Timestamped by \[dq]CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US\[dq] on Tue Sep 12 20:08:49 UTC 2017 - Timestamp digest algorithm: SHA-1 - Timestamp signature algorithm: SHA1withRSA, 2048-bit key - -jar verified. - -The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29. -\f[R] -.fi -.SH EXAMPLE OF VERIFICATION WITH CERTIFICATE INFORMATION -.PP -If you specify the \f[V]-certs\f[R] option with the \f[V]-verify\f[R] -and \f[V]-verbose\f[R] options, then the output includes certificate -information for each signer of the JAR file. -The information includes the certificate type, the signer distinguished -name information (when it is an X.509 certificate), and in parentheses, -the keystore alias for the signer when the public key certificate in the -JAR file matches the one in a keystore entry, for example: -.IP -.nf -\f[CB] -jarsigner -keystore $JAVA_HOME/lib/security/cacerts -verify -verbose -certs ButtonDemo.jar - -s k 866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF - - >>> Signer - X.509, CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US - [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM] - X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US - [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM] - X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU=\[dq](c) 2006 VeriSign, Inc. - For authorized use only\[dq], OU=VeriSign Trust Network, O=\[dq]VeriSign, Inc.\[dq], C=US (verisignclass3g5ca [jdk]) - [trusted certificate] - >>> TSA - X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US - [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM] - X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US - [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM] - - 825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF - 7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA - 0 Tue Sep 12 20:07:54 EDT 2017 META-INF/ - 0 Tue Sep 12 20:07:16 EDT 2017 components/ - 0 Tue Sep 12 20:07:16 EDT 2017 components/images/ -smk 523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class - - [entry was signed on 2017-09-12, 4:08 PM] - >>> Signer - X.509, CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US - [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM] - X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US - [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM] - X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU=\[dq](c) 2006 VeriSign, Inc. - For authorized use only\[dq], OU=VeriSign Trust Network, O=\[dq]VeriSign, Inc.\[dq], C=US (verisignclass3g5ca [jdk]) - [trusted certificate] - >>> TSA - X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US - [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM] - X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US - [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM] - -smk 3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class -\&... -smk 2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp -\&... -smk 172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif -\&... -smk 235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif -\&... -smk 172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif -\&... - - s = signature was verified - m = entry is listed in manifest - k = at least one certificate was found in keystore - -- Signed by \[dq]CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US\[dq] - Digest algorithm: SHA-256 - Signature algorithm: SHA256withRSA, 2048-bit key - Timestamped by \[dq]CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US\[dq] on Tue Sep 12 20:08:49 UTC 2017 - Timestamp digest algorithm: SHA-1 - Timestamp signature algorithm: SHA1withRSA, 2048-bit key - -jar verified. - -The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29. -\f[R] -.fi -.PP -If the certificate for a signer isn\[aq]t an X.509 certificate, then -there is no distinguished name information. -In that case, just the certificate type and the alias are shown. -For example, if the certificate is a PGP certificate, and the alias is -\f[V]bob\f[R], then you would get: \f[V]PGP, (bob)\f[R]. diff --git a/src/jdk.jartool/share/man/jarsigner.md b/src/jdk.jartool/share/man/jarsigner.md new file mode 100644 index 00000000000..9542c0fda60 --- /dev/null +++ b/src/jdk.jartool/share/man/jarsigner.md @@ -0,0 +1,1089 @@ +--- +# Copyright (c) 1998, 2024, 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. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# 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. +# + +title: 'JARSIGNER(1) JDK @@VERSION_SHORT@@ | JDK Commands' +date: @@COPYRIGHT_YEAR@@ +lang: en +--- + +## Name + +jarsigner - sign and verify Java Archive (JAR) files + +## Synopsis + +`jarsigner` \[*options*\] *jar-file* *alias* + +`jarsigner` `-verify` \[*options*\] *jar-file* \[*alias* ...\] + +`jarsigner` `-version` + +*options* +: The command-line options. See [Options for jarsigner]. + +`-verify` +: The `-verify` option can take zero or more keystore alias names after the + JAR file name. When the `-verify` option is specified, the `jarsigner` + command checks that the certificate used to verify each signed entry in the + JAR file matches one of the keystore aliases. The aliases are defined in + the keystore specified by `-keystore` or the default keystore. + + If you also specify the `-strict` option, and the `jarsigner` command + detects severe warnings, the message, "jar verified, with signer errors" is + displayed. + +*jar-file* +: The JAR file to be signed. + + If you also specified the `-strict` option, and the `jarsigner` command + detected severe warnings, the message, "jar signed, with signer errors" is + displayed. + +*alias* +: The aliases are defined in the keystore specified by `-keystore` or the + default keystore. + +`-version` +: The `-version` option prints the program version of `jarsigner`. + +## Description + +The `jarsigner` tool has two purposes: + +- To sign Java Archive (JAR) files. + +- To verify the signatures and integrity of signed JAR files. + +The JAR feature enables the packaging of class files, images, sounds, and other +digital data in a single file for faster and easier distribution. A tool named +`jar` enables developers to produce JAR files. (Technically, any ZIP file can +also be considered a JAR file, although when created by the `jar` command or +processed by the `jarsigner` command, JAR files also contain a +`META-INF/MANIFEST.MF` file.) + +A digital signature is a string of bits that is computed from some data (the +data being signed) and the private key of an entity (a person, company, and so +on). Similar to a handwritten signature, a digital signature has many useful +characteristics: + +- Its authenticity can be verified by a computation that uses the public key + corresponding to the private key used to generate the signature. + +- It can't be forged, assuming the private key is kept secret. + +- It is a function of the data signed and thus can't be claimed to be the + signature for other data as well. + +- The signed data can't be changed. If the data is changed, then the + signature can't be verified as authentic. + +To generate an entity's signature for a file, the entity must first have a +public/private key pair associated with it and one or more certificates that +authenticate its public key. A certificate is a digitally signed statement from +one entity that says that the public key of another entity has a particular +value. + +The `jarsigner` command uses key and certificate information from a keystore to +generate digital signatures for JAR files. A keystore is a database of private +keys and their associated X.509 certificate chains that authenticate the +corresponding public keys. The `keytool` command is used to create and +administer keystores. + +The `jarsigner` command uses an entity's private key to generate a signature. +The signed JAR file contains, among other things, a copy of the certificate +from the keystore for the public key corresponding to the private key used to +sign the file. The `jarsigner` command can verify the digital signature of the +signed JAR file using the certificate inside it (in its signature block file). + +The `jarsigner` command can generate signatures that include a time stamp that +enables a systems or deployer to check whether the JAR file was signed while +the signing certificate was still valid. + +In addition, APIs allow applications to obtain the timestamp information. + +At this time, the `jarsigner` command can only sign JAR files created by the +`jar` command or zip files. JAR files are the same as zip files, except they +also have a `META-INF/MANIFEST.MF` file. A `META-INF/MANIFEST.MF` file is +created when the `jarsigner` command signs a zip file. + +The default `jarsigner` command behavior is to sign a JAR or zip file. Use the +`-verify` option to verify a signed JAR file. + +The `jarsigner` command also attempts to validate the signer's certificate +after signing or verifying. During validation, it checks the revocation +status of each certificate in the signer's certificate chain when the +`-revCheck` option is specified. If there is a validation error or any other +problem, the command generates warning messages. If you specify the `-strict` +option, then the command treats severe warnings as errors. See [Errors and +Warnings]. + +## Keystore Aliases + +All keystore entities are accessed with unique aliases. + +When you use the `jarsigner` command to sign a JAR file, you must specify the +alias for the keystore entry that contains the private key needed to generate +the signature. If no output file is specified, it overwrites the original JAR +file with the signed JAR file. + +Keystores are protected with a password, so the store password must be +specified. You are prompted for it when you don't specify it on the command +line. Similarly, private keys are protected in a keystore with a password, so +the private key's password must be specified, and you are prompted for the +password when you don't specify it on the command line and it isn't the same as +the store password. + +## Keystore Location + +The `jarsigner` command has a `-keystore` option for specifying the URL of the +keystore to be used. The keystore is by default stored in a file named +`.keystore` in the user's home directory, as determined by the `user.home` +system property. + +**Linux and macOS:** `user.home` defaults to the user's home +directory. + +The input stream from the `-keystore` option is passed to the `KeyStore.load` +method. If `NONE` is specified as the URL, then a null stream is passed to the +`KeyStore.load` method. `NONE` should be specified when the `KeyStore` class +isn't file based, for example, when it resides on a hardware token device. + +## Keystore Implementation + +The `KeyStore` class provided in the `java.security` package supplies a number +of well-defined interfaces to access and modify the information in a keystore. +You can have multiple different concrete implementations, where each +implementation is for a particular type of keystore. + +Currently, there are two command-line tools that use keystore implementations +(`keytool` and `jarsigner`). + +The default keystore implementation is `PKCS12`. This is a cross platform +keystore based on the RSA PKCS12 Personal Information Exchange Syntax Standard. +This standard is primarily meant for storing or transporting a user's private +keys, certificates, and miscellaneous secrets. There is another built-in +implementation, provided by Oracle. It implements the keystore as a file with a +proprietary keystore type (format) named `JKS`. It protects each private key +with its individual password, and also protects the integrity of the entire +keystore with a (possibly different) password. + +Keystore implementations are provider-based, which means the application +interfaces supplied by the `KeyStore` class are implemented in terms of a +Service Provider Interface (SPI). There is a corresponding abstract +`KeystoreSpi` class, also in the `java.security package`, that defines the +Service Provider Interface methods that providers must implement. The term +provider refers to a package or a set of packages that supply a concrete +implementation of a subset of services that can be accessed by the Java +Security API. To provide a keystore implementation, clients must implement a +provider and supply a `KeystoreSpi` subclass implementation, as described in +[How to Implement a Provider in the Java Cryptography Architecture]( +https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase&id=security_guide_implement_provider_jca). + +Applications can choose different types of keystore implementations from +different providers, with the `getInstance` factory method in the `KeyStore` +class. A keystore type defines the storage and data format of the keystore +information and the algorithms used to protect private keys in the keystore and +the integrity of the keystore itself. Keystore implementations of different +types aren't compatible. + +The `jarsigner` commands can read file-based keystores from any location that +can be specified using a URL. In addition, these commands can read +non-file-based keystores such as those provided by MSCAPI on Windows and PKCS11 +on all platforms. + +For the `jarsigner` and `keytool` commands, you can specify a keystore type at +the command line with the `-storetype` option. + +If you don't explicitly specify a keystore type, then the tools choose a +keystore implementation based on the value of the `keystore.type` property +specified in the security properties file. The security properties file is +called `java.security`, and it resides in the JDK security properties +directory, `java.home/conf/security`. + +Each tool gets the `keystore.type` value and then examines all the installed +providers until it finds one that implements keystores of that type. It then +uses the keystore implementation from that provider. + +The `KeyStore` class defines a static method named `getDefaultType` that lets +applications retrieve the value of the `keystore.type` property. The following +line of code creates an instance of the default keystore type as specified in +the `keystore.type` property: + +> `KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());` + +The default keystore type is `pkcs12`, which is a cross platform keystore based +on the RSA PKCS12 Personal Information Exchange Syntax Standard. This is +specified by the following line in the security properties file: + +> `keystore.type=pkcs12` + +Case doesn't matter in keystore type designations. For example, `JKS` is the +same as `jks`. + +To have the tools utilize a keystore implementation other than the default, you +can change that line to specify a different keystore type. For example, if you +want to use the Oracle's `jks` keystore implementation, then change the line to +the following: + +> `keystore.type=jks` + +## Supported Algorithms + +By default, the `jarsigner` command signs a JAR file using one of the following +algorithms and block file extensions depending on the type and size of +the private key: + +Table: Default Signature Algorithms and Block File Extensions + +keyalg key size default sigalg block file extension +------- -------- -------------- -------------------- +DSA any size SHA256withDSA .DSA +RSA \< 624 SHA256withRSA .RSA + \<= 7680 SHA384withRSA + \> 7680 SHA512withRSA +EC \< 512 SHA384withECDSA .EC + \>= 512 SHA512withECDSA +RSASSA-PSS \< 624 RSASSA-PSS (with SHA-256) .RSA + \<= 7680 RSASSA-PSS (with SHA-384) + \> 7680 RSASSA-PSS (with SHA-512) +EdDSA 255 Ed25519 .EC + 448 Ed448 +------- -------- -------------- ------ + +* If an RSASSA-PSS key is encoded with parameters, then jarsigner will use the +same parameters in the signature. Otherwise, jarsigner will use parameters that +are determined by the size of the key as specified in the table above. +For example, an 3072-bit RSASSA-PSS key will use RSASSA-PSS as the signature +algorithm and SHA-384 as the hash and MGF1 algorithms. + +* If a key algorithm is not listed in this table, the `.DSA` extension +is used when signing a JAR file. + +These default signature algorithms can be overridden by using the `-sigalg` +option. + +The `jarsigner` command uses the `jdk.jar.disabledAlgorithms` and +`jdk.security.legacyAlgorithms` security properties to determine which +algorithms are considered a security risk. If the JAR file was signed +with any algorithms that are disabled, it will be treated as an unsigned JAR +file. If the JAR file was signed with any legacy algorithms, it will be treated +as signed with an informational warning to inform users that the legacy +algorithm will be disabled in a future update. +For detailed verification output, include `-J-Djava.security.debug=jar`. +The `jdk.jar.disabledAlgorithms` and `jdk.security.legacyAlgorithms` +security properties are defined in the `java.security` file (located in +the JDK's `$JAVA_HOME/conf/security` directory). + +**Note:** + +In order to improve out of the box security, default key size and signature +algorithm names are periodically updated to stronger values with each release +of the JDK. If interoperability with older releases of the JDK is important, +please make sure the defaults are supported by those releases, or alternatively +use the `-sigalg` option to override the default values at your own risk. + +## The Signed JAR File + +When the `jarsigner` command is used to sign a JAR file, the output signed JAR +file is exactly the same as the input JAR file, except that it has two +additional files placed in the META-INF directory: + +- A signature file with an `.SF` extension + +- A signature block file with a `.DSA`, `.RSA`, or `.EC` extension + +The base file names for these two files come from the value of the `-sigfile` +option. For example, when the option is `-sigfile MKSIGN`, the files are named +`MKSIGN.SF` and `MKSIGN.RSA`. In this document, we assume the signer always +uses an RSA key. + +If no `-sigfile` option appears on the command line, then the base file name +for the `.SF` and the signature block files is the first 8 characters of the alias name +specified on the command line, all converted to uppercase. If the alias name +has fewer than 8 characters, then the full alias name is used. If the alias +name contains any characters that aren't allowed in a signature file name, then +each such character is converted to an underscore (\_) character in forming the +file name. Valid characters include letters, digits, underscores, and hyphens. + +## Signature File + +A signature file (`.SF` file) looks similar to the manifest file that is always +included in a JAR file when the `jarsigner` command is used to sign the file. +For each source file included in the JAR file, the `.SF` file has two lines, +such as in the manifest file, that list the following: + +- File name + +- Name of the digest algorithm (SHA) + +- SHA digest value + +**Note:** + +The name of the digest algorithm (SHA) and the SHA digest value are on the same +line. + +In the manifest file, the SHA digest value for each source file is the digest +(hash) of the binary data in the source file. In the `.SF` file, the digest +value for a specified source file is the hash of the two lines in the manifest +file for the source file. + +The signature file, by default, includes a header with a hash of the whole +manifest file. The header also contains a hash of the manifest header. The +presence of the header enables verification optimization. See [JAR File +Verification]. + +## Signature Block File + +The `.SF` file is signed and the signature is placed in the signature block +file. This file also contains, encoded inside it, the certificate or +certificate chain from the keystore that authenticates the public key +corresponding to the private key used for signing. The file has the extension +`.DSA`, `.RSA`, or `.EC`, depending on the key algorithm used. See the table +in [Supported Algorithms]. + +## Signature Time Stamp + +The `jarsigner` command used with the following options generates and stores a +signature time stamp when signing a JAR file: + +- `-tsa` *url* + +- `-tsacert` *alias* + +- `-tsapolicyid` *policyid* + +- `-tsadigestalg` *algorithm* + +See [Options for jarsigner]. + +## JAR File Verification + +A successful JAR file verification occurs when the signatures are valid, and +none of the files that were in the JAR file when the signatures were generated +have changed since then. JAR file verification involves the following steps: + +1. Verify the signature of the `.SF` file. + + The verification ensures that the signature stored in each signature block + file was generated using the private key corresponding to the + public key whose certificate (or certificate chain) also appears in the + signature block file. It also ensures that the signature is a valid signature of the + corresponding signature (`.SF`) file, and thus the `.SF` file wasn't + tampered with. + +2. Verify the digest listed in each entry in the `.SF` file with each + corresponding section in the manifest. + + The `.SF` file by default includes a header that contains a hash of the + entire manifest file. When the header is present, the verification can + check to see whether or not the hash in the header matches the hash of the + manifest file. If there is a match, then verification proceeds to the next + step. + + If there is no match, then a less optimized verification is required to + ensure that the hash in each source file information section in the `.SF` + file equals the hash of its corresponding section in the manifest file. See + Signature File. + + One reason the hash of the manifest file that is stored in the `.SF` file + header might not equal the hash of the current manifest file is that it + might contain sections for newly added files after the file was signed. For + example, suppose one or more files were added to the signed JAR file (using + the `jar` tool) that already contains a signature and a `.SF` file. If the + JAR file is signed again by a different signer, then the manifest file is + changed (sections are added to it for the new files by the `jarsigner` tool) + and a new `.SF` file is created, but the original `.SF` file is unchanged. A + verification is still considered successful if none of the files that were + in the JAR file when the original signature was generated have been changed + since then. This is because the hashes in the non-header sections of the + `.SF` file equal the hashes of the corresponding sections in the manifest + file. + +3. Read each file in the JAR file that has an entry in the `.SF` file. While + reading, compute the file's digest and compare the result with the digest + for this file in the manifest section. The digests should be the same or + verification fails. + + If any serious verification failures occur during the verification process, + then the process is stopped and a security exception is thrown. The + `jarsigner` command catches and displays the exception. + +4. Check for disabled algorithm usage. See [Supported Algorithms]. + +**Note:** + +You should read any addition warnings (or errors if you specified the `-strict` +option), as well as the content of the certificate (by specifying the +`-verbose` and `-certs` options) to determine if the signature can be trusted. + +## Multiple Signatures for a JAR File + +A JAR file can be signed by multiple people by running the `jarsigner` command +on the file multiple times and specifying the alias for a different person each +time, as follows: + +``` +jarsigner myBundle.jar susan +jarsigner myBundle.jar kevin +``` + +When a JAR file is signed multiple times, there are multiple `.SF` and signature +block files in the resulting JAR file, one pair for each signature. In the previous +example, the output JAR file includes files with the following names: + +``` +SUSAN.SF +SUSAN.RSA +KEVIN.SF +KEVIN.RSA +``` + +## Options for jarsigner + +The following sections describe the options for the `jarsigner`. Be aware of +the following standards: + +- All option names are preceded by a hyphen sign (-). + +- The options can be provided in any order. + +- Items that are in italics or underlined (option values) represent the + actual values that must be supplied. + +- The `-storepass`, `-keypass`, `-sigfile`, `-sigalg`, `-digestalg`, + `-signedjar`, and TSA-related options are only relevant when signing a JAR + file; they aren't relevant when verifying a signed JAR file. The + `-keystore` option is relevant for signing and verifying a JAR file. In + addition, aliases are specified when signing and verifying a JAR file. + +`-keystore` *url* +: Specifies the URL that tells the keystore location. This defaults to the + file `.keystore` in the user's home directory, as determined by the + `user.home` system property. + + A keystore is required when signing. You must explicitly specify a keystore + when the default keystore doesn't exist or if you want to use one other + than the default. + + A keystore isn't required when verifying, but if one is specified or the + default exists and the `-verbose` option was also specified, then + additional information is output regarding whether or not any of the + certificates used to verify the JAR file are contained in that keystore. + + The `-keystore` argument can be a file name and path specification rather + than a URL, in which case it is treated the same as a file: URL, for + example, the following are equivalent: + + - `-keystore` *filePathAndName* + + - `-keystore file:`*filePathAndName* + + If the Sun PKCS \#11 provider was configured in the `java.security` + security properties file (located in the JDK's `$JAVA_HOME/conf/security` + directory), then the `keytool` and `jarsigner` tools can operate on the + PKCS \#11 token by specifying these options: + + > `-keystore NONE -storetype PKCS11` + + For example, the following command lists the contents of the configured + PKCS\#11 token: + + > `keytool -keystore NONE -storetype PKCS11 -list` + +`-storepass` \[`:env` \| `:file`\] *argument* +: Specifies the password that is required to access the keystore. This is + only needed when signing (not verifying) a JAR file. In that case, if a + `-storepass` option isn't provided at the command line, then the user is + prompted for the password. + + If the modifier `env` or `file` isn't specified, then the password has the + value `argument`. Otherwise, the password is retrieved as follows: + + - `env`: Retrieve the password from the environment variable named + *argument*. + + - `file`: Retrieve the password from the file named *argument*. + + **Note:** + + The password shouldn't be specified on the command line or in a script + unless it is for testing purposes, or you are on a secure system. + +`-storetype` *storetype* +: Specifies the type of keystore to be instantiated. The default keystore + type is the one that is specified as the value of the `keystore.type` + property in the security properties file, which is returned by the static + `getDefaultType` method in `java.security.KeyStore`. + + The PIN for a PKCS \#11 token can also be specified with the `-storepass` + option. If none is specified, then the `keytool` and `jarsigner` commands + prompt for the token PIN. If the token has a protected authentication path + (such as a dedicated PIN-pad or a biometric reader), then the `-protected` + option must be specified and no password options can be specified. + +`-keypass` \[`:env` \| `:file`\] *argument* `-certchain` *file* +: Specifies the password used to protect the private key of the keystore + entry addressed by the alias specified on the command line. The password is + required when using `jarsigner` to sign a JAR file. If no password is + provided on the command line, and the required password is different from + the store password, then the user is prompted for it. + + If the modifier `env` or `file` isn't specified, then the password has the + value `argument`. Otherwise, the password is retrieved as follows: + + - `env`: Retrieve the password from the environment variable named + *argument*. + + - `file`: Retrieve the password from the file named *argument*. + + **Note:** + + The password shouldn't be specified on the command line or in a script + unless it is for testing purposes, or you are on a secure system. + +`-certchain` *file* +: Specifies the certificate chain to be used when the certificate chain + associated with the private key of the keystore entry that is addressed by + the alias specified on the command line isn't complete. This can happen + when the keystore is located on a hardware token where there isn't enough + capacity to hold a complete certificate chain. The file can be a sequence + of concatenated X.509 certificates, or a single PKCS\#7 formatted data + block, either in binary encoding format or in printable encoding format + (also known as Base64 encoding) as defined by [Internet RFC 1421 + Certificate Encoding Standard](http://tools.ietf.org/html/rfc1421). + +`-sigfile` *file* +: Specifies the base file name to be used for the generated `.SF` and signature block + files. For example, if file is `DUKESIGN`, then the generated `.SF` and + signature block files are named `DUKESIGN.SF` and `DUKESIGN.RSA`, and placed in the + `META-INF` directory of the signed JAR file. + + The characters in the file must come from the set `a-zA-Z0-9_-`. Only + letters, numbers, underscore, and hyphen characters are allowed. All + lowercase characters are converted to uppercase for the `.SF` and signature block + file names. + + If no `-sigfile` option appears on the command line, then the base file + name for the `.SF` and signature block files is the first 8 characters of the alias + name specified on the command line, all converted to upper case. If the + alias name has fewer than 8 characters, then the full alias name is used. + If the alias name contains any characters that aren't valid in a signature + file name, then each such character is converted to an underscore (\_) + character to form the file name. + +`-signedjar` *file* +: Specifies the name of signed JAR file. + +`-digestalg` *algorithm* +: Specifies the name of the message digest algorithm to use when digesting + the entries of a JAR file. + + For a list of standard message digest algorithm names, see the Java Security + Standard Algorithm Names Specification. + + If this option isn't specified, then `SHA-384` is used. There must either be + a statically installed provider supplying an implementation of the + specified algorithm or the user must specify one with the `-addprovider` or + `-providerClass` options; otherwise, the command will not succeed. + +`-sigalg` *algorithm* +: Specifies the name of the signature algorithm to use to sign the JAR file. + + This algorithm must be compatible with the private key used to sign the + JAR file. If this option isn't specified, then use a default algorithm + matching the private key as described in the [Supported Algorithms] + section. There must either be a statically installed provider supplying an + implementation of the specified algorithm or you must specify one with the + `-addprovider` or `-providerClass` option; otherwise, the command doesn't + succeed. + + For a list of standard signature algorithm names, see the Java Security + Standard Algorithm Names Specification. + +`-verify` +: Verifies a signed JAR file. + +`-verbose`\[`:`*suboptions*\] +: When the `-verbose` option appears on the command line, it indicates that + the `jarsigner` use the verbose mode when signing or verifying with the + suboptions determining how much information is shown. This causes the , + which causes `jarsigner` to output extra information about the progress of + the JAR signing or verification. The *suboptions* can be `all`, `grouped`, + or `summary`. + + If the `-certs` option is also specified, then the default mode (or + suboption `all`) displays each entry as it is being processed, and after + that, the certificate information for each signer of the JAR file. + + If the `-certs` and the `-verbose:grouped` suboptions are specified, then + entries with the same signer info are grouped and displayed together with + their certificate information. + + If `-certs` and the `-verbose:summary` suboptions are specified, then + entries with the same signer information are grouped and displayed together + with their certificate information. + + Details about each entry are summarized and displayed as *one entry (and + more)*. See [Example of Verifying a Signed JAR File] and [Example of + Verification with Certificate Information]. + +`-certs` +: If the `-certs` option appears on the command line with the `-verify` and + `-verbose` options, then the output includes certificate information for + each signer of the JAR file. This information includes the name of the type + of certificate (stored in the signature block file) that certifies the signer's + public key, and if the certificate is an X.509 certificate (an instance of + the `java.security.cert.X509Certificate`), then the distinguished name of + the signer. + + The keystore is also examined. If no keystore value is specified on the + command line, then the default keystore file (if any) is checked. If the + public key certificate for a signer matches an entry in the keystore, then + the alias name for the keystore entry for that signer is displayed in + parentheses. + +`-revCheck` +: This option enables revocation checking of certificates when signing or + verifying a JAR file. The `jarsigner` command attempts to make network + connections to fetch OCSP responses and CRLs if the `-revCheck` option + is specified on the command line. Note that revocation checks are not + enabled unless this option is specified. + +`-tsa` *url* +: If `-tsa http://example.tsa.url` appears on the command line when signing a + JAR file then a time stamp is generated for the signature. The URL, + `http://example.tsa.url`, identifies the location of the Time Stamping + Authority (TSA) and overrides any URL found with the `-tsacert` option. The + `-tsa` option doesn't require the TSA public key certificate to be present + in the keystore. + + To generate the time stamp, `jarsigner` communicates with the TSA with the + Time-Stamp Protocol (TSP) defined in RFC 3161. When successful, the time + stamp token returned by the TSA is stored with the signature in the + signature block file. + +`-tsacert` *alias* +: When `-tsacert` *alias* appears on the command line when signing a JAR + file, a time stamp is generated for the signature. The alias identifies the + TSA public key certificate in the keystore that is in effect. The entry's + certificate is examined for a Subject Information Access extension that + contains a URL identifying the location of the TSA. + + The TSA public key certificate must be present in the keystore when using + the `-tsacert` option. + +`-tsapolicyid` *policyid* +: Specifies the object identifier (OID) that identifies the policy ID to be + sent to the TSA server. If this option isn't specified, no policy ID is + sent and the TSA server will choose a default policy ID. + + Object identifiers are defined by X.696, which is an ITU Telecommunication + Standardization Sector (ITU-T) standard. These identifiers are typically + period-separated sets of non-negative digits like `1.2.3.4`, for example. + +`-tsadigestalg` *algorithm* +: Specifies the message digest algorithm that is used to generate the message + imprint to be sent to the TSA server. If this option isn't specified, + SHA-384 will be used. + + See [Supported Algorithms]. + + For a list of standard message digest algorithm names, see the Java Security + Standard Algorithm Names Specification. + +`-internalsf` +: In the past, the signature block file generated when a JAR file + was signed included a complete encoded copy of the `.SF` file (signature + file) also generated. This behavior has been changed. To reduce the overall + size of the output JAR file, the signature block file by default doesn't contain a + copy of the `.SF` file anymore. If `-internalsf` appears on the command + line, then the old behavior is utilized. This option is useful for testing. + In practice, don't use the `-internalsf` option because it incurs higher + overhead. + +`-sectionsonly` +: If the `-sectionsonly` option appears on the command line, then the `.SF` + file (signature file) generated when a JAR file is signed doesn't include a + header that contains a hash of the whole manifest file. It contains only + the information and hashes related to each individual source file included + in the JAR file. See Signature File. + + By default, this header is added, as an optimization. When the header is + present, whenever the JAR file is verified, the verification can first + check to see whether the hash in the header matches the hash of the whole + manifest file. When there is a match, verification proceeds to the next + step. When there is no match, it is necessary to do a less optimized + verification that the hash in each source file information section in the + `.SF` file equals the hash of its corresponding section in the manifest + file. See [JAR File Verification]. + + The `-sectionsonly` option is primarily used for testing. It shouldn't be + used other than for testing because using it incurs higher overhead. + +`-protected` +: Values can be either `true` or `false`. Specify `true` when a password must + be specified through a protected authentication path such as a dedicated + PIN reader. + +`-providerName` *providerName* +: If more than one provider was configured in the `java.security` security + properties file, then you can use the `-providerName` option to target a + specific provider instance. The argument to this option is the name of the + provider. + + For the Oracle PKCS \#11 provider, *providerName* is of the form + `SunPKCS11-`*TokenName*, where *TokenName* is the name suffix that the + provider instance has been configured with, as detailed in the + configuration attributes table. For example, the following command lists + the contents of the `PKCS #11` keystore provider instance with name suffix + `SmartCard`: + + > `jarsigner -keystore NONE -storetype PKCS11 -providerName + SunPKCS11-SmartCard -list` + +`-addprovider` *name* \[`-providerArg` *arg*\] +: Adds a security provider by name (such as SunPKCS11) and an optional + configure argument. The value of the security provider is the name of a + security provider that is defined in a module. + + Used with the `-providerArg ConfigFilePath` option, the `keytool` and + `jarsigner` tools install the provider dynamically and use `ConfigFilePath` + for the path to the token configuration file. The following example shows a + command to list a `PKCS #11` keystore when the Oracle PKCS \#11 provider + wasn't configured in the security properties file. + + > `jarsigner -keystore NONE -storetype PKCS11 -addprovider SunPKCS11 + -providerArg /mydir1/mydir2/token.config` + +`-providerClass` *provider-class-name* \[`-providerArg` *arg*\] +: Used to specify the name of cryptographic service provider's master class + file when the service provider isn't listed in the `java.security` security + properties file. Adds a security provider by fully-qualified class name and + an optional configure argument. + + **Note:** + + The preferred way to load PKCS11 is by using modules. See `-addprovider`. + +`-providerPath` *classpath* +: Used to specify the classpath for providers specified by the `-providerClass` + option. Multiple paths should be separated by the system-dependent + path-separator character. + +`-J`*javaoption* +: Passes through the specified *javaoption* string directly to the Java + interpreter. The `jarsigner` command is a wrapper around the interpreter. + This option shouldn't contain any spaces. It is useful for adjusting the + execution environment or memory usage. For a list of possible interpreter + options, type `java -h` or `java -X` at the command line. + +`-strict` +: During the signing or verifying process, the command may issue warning + messages. If you specify this option, the exit code of the tool reflects + the severe warning messages that this command found. See [Errors and + Warnings]. + +`-conf` *url* +: Specifies a pre-configured options file. Read the + [keytool documentation](keytool.html#pre-configured-options-file) for + details. The property keys supported are "jarsigner.all" for all actions, + "jarsigner.sign" for signing, and "jarsigner.verify" for verification. + `jarsigner` arguments including the JAR file name and alias name(s) cannot + be set in this file. + +`-version` +: Prints the program version. + +## Errors and Warnings + +During the signing or verifying process, the `jarsigner` command may issue +various errors or warnings. + +If there is a failure, the `jarsigner` command exits with code 1. If there is +no failure, but there are one or more severe warnings, the `jarsigner` command +exits with code 0 when the `-strict` option is **not** specified, or exits with +the OR-value of the warning codes when the `-strict` is specified. If there is +only informational warnings or no warning at all, the command always exits with +code 0. + +For example, if a certificate used to sign an entry is expired and has a +KeyUsage extension that doesn't allow it to sign a file, the `jarsigner` +command exits with code 12 (=4+8) when the `-strict` option is specified. + +**Note:** Exit codes are reused because only the values from 0 to 255 are legal +on Linux and macOS. + +The following sections describes the names, codes, and descriptions of the +errors and warnings that the `jarsigner` command can issue. + +## Failure + +Reasons why the `jarsigner` command fails include (but aren't limited to) a +command line parsing error, the inability to find a keypair to sign the JAR +file, or the verification of a signed JAR fails. + +failure +: Code 1. The signing or verifying fails. + +## Severe Warnings + +**Note:** + +Severe warnings are reported as errors if you specify the `-strict` option. + +Reasons why the `jarsigner` command issues a severe warning include the +certificate used to sign the JAR file has an error or the signed JAR file has +other problems. + +hasExpiredCert +: Code 4. This JAR contains entries whose signer certificate has expired. + +hasExpiredTsaCert +: Code 4. The timestamp has expired. + +notYetValidCert +: Code 4. This JAR contains entries whose signer certificate isn't yet valid. + +chainNotValidated +: Code 4. This JAR contains entries whose certificate chain isn't validated. + +tsaChainNotValidated +: Code 64. The timestamp is invalid. + +signerSelfSigned +: Code 4. This JAR contains entries whose signer certificate is self signed. + +disabledAlg +: Code 4. An algorithm used is considered a security risk and is disabled. + +badKeyUsage +: Code 8. This JAR contains entries whose signer certificate's KeyUsage + extension doesn't allow code signing. + +badExtendedKeyUsage +: Code 8. This JAR contains entries whose signer certificate's + ExtendedKeyUsage extension doesn't allow code signing. + +badNetscapeCertType +: Code 8. This JAR contains entries whose signer certificate's + NetscapeCertType extension doesn't allow code signing. + +hasUnsignedEntry +: Code 16. This JAR contains unsigned entries which haven't been + integrity-checked. + +notSignedByAlias +: Code 32. This JAR contains signed entries which aren't signed by the + specified alias(es). + +aliasNotInStore +: Code 32. This JAR contains signed entries that aren't signed by alias in + this keystore. + +tsaChainNotValidated +: Code 64. This JAR contains entries whose TSA certificate chain is invalid. + +## Informational Warnings + +Informational warnings include those that aren't errors but regarded as bad +practice. They don't have a code. + +extraAttributesDetected +: The POSIX file permissions and/or symlink attributes are detected during + signing or verifying a JAR file. The `jarsigner` tool preserves these + attributes in the newly signed file but warns that these attributes are + unsigned and not protected by the signature. + +hasExpiringCert +: This JAR contains entries whose signer certificate expires within six + months. + +hasExpiringTsaCert +: The timestamp will expire within one year on `YYYY-MM-DD`. + +hasNonexistentEntries +: This JAR contains signed entries for files that do not exist. + +legacyAlg +: An algorithm used is considered a security risk but not disabled. + +noTimestamp +: This JAR contains signatures that doesn't include a timestamp. Without a + timestamp, users may not be able to validate this JAR file after the signer + certificate's expiration date (`YYYY-MM-DD`) or after any future revocation + date. + +## Example of Signing a JAR File + +Use the following command to sign `bundle.jar` with the private key of a user +whose keystore alias is `jane` in a keystore named `mystore` in the `working` +directory and name the signed JAR file `sbundle.jar`: + +> `jarsigner -keystore /working/mystore -storepass` *keystore\_password* + `-keypass` *private\_key\_password* `-signedjar sbundle.jar bundle.jar + jane` + +There is no `-sigfile` specified in the previous command so the generated `.SF` +and signature block files to be placed in the signed JAR file have default names based +on the alias name. They are named `JANE.SF` and `JANE.RSA`. + +If you want to be prompted for the store password and the private key password, +then you could shorten the previous command to the following: + +> `jarsigner -keystore /working/mystore -signedjar sbundle.jar bundle.jar + jane` + +If the `keystore` is the default `keystore` (`.keystore` in your home +directory), then you don't need to specify a `keystore`, as follows: + +> `jarsigner -signedjar sbundle.jar bundle.jar jane` + +If you want the signed JAR file to overwrite the input JAR file (`bundle.jar`), +then you don't need to specify a `-signedjar` option, as follows: + +> `jarsigner bundle.jar jane` + +## Example of Verifying a Signed JAR File + +To verify a signed JAR file to ensure that the signature is valid and the JAR +file wasn't been tampered with, use a command such as the following: + +> `jarsigner -verify ButtonDemo.jar` + +When the verification is successful, `jar verified` is displayed. Otherwise, an +error message is displayed. You can get more information when you use the +`-verbose` option. A sample use of `jarsigner` with the `-verbose` option +follows: + +``` +jarsigner -verify -verbose ButtonDemo.jar + +s 866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF + 825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF + 7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA + 0 Tue Sep 12 20:07:54 EDT 2017 META-INF/ + 0 Tue Sep 12 20:07:16 EDT 2017 components/ + 0 Tue Sep 12 20:07:16 EDT 2017 components/images/ +sm 523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class +sm 3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class +sm 2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp +sm 172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif +sm 235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif +sm 172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif + + s = signature was verified + m = entry is listed in manifest + k = at least one certificate was found in keystore + +- Signed by "CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US" + Digest algorithm: SHA-256 + Signature algorithm: SHA256withRSA, 2048-bit key + Timestamped by "CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US" on Tue Sep 12 20:08:49 UTC 2017 + Timestamp digest algorithm: SHA-1 + Timestamp signature algorithm: SHA1withRSA, 2048-bit key + +jar verified. + +The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29. +``` + +## Example of Verification with Certificate Information + +If you specify the `-certs` option with the `-verify` and `-verbose` options, +then the output includes certificate information for each signer of the JAR +file. The information includes the certificate type, the signer distinguished +name information (when it is an X.509 certificate), and in parentheses, the +keystore alias for the signer when the public key certificate in the JAR file +matches the one in a keystore entry, for example: + +``` +jarsigner -keystore $JAVA_HOME/lib/security/cacerts -verify -verbose -certs ButtonDemo.jar + +s k 866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF + + >>> Signer + X.509, CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US + [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM] + X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US + [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM] + X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU="(c) 2006 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US (verisignclass3g5ca [jdk]) + [trusted certificate] + >>> TSA + X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US + [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM] + X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US + [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM] + + 825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF + 7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA + 0 Tue Sep 12 20:07:54 EDT 2017 META-INF/ + 0 Tue Sep 12 20:07:16 EDT 2017 components/ + 0 Tue Sep 12 20:07:16 EDT 2017 components/images/ +smk 523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class + + [entry was signed on 2017-09-12, 4:08 PM] + >>> Signer + X.509, CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US + [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM] + X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US + [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM] + X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU="(c) 2006 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US (verisignclass3g5ca [jdk]) + [trusted certificate] + >>> TSA + X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US + [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM] + X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US + [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM] + +smk 3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class +... +smk 2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp +... +smk 172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif +... +smk 235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif +... +smk 172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif +... + + s = signature was verified + m = entry is listed in manifest + k = at least one certificate was found in keystore + +- Signed by "CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US" + Digest algorithm: SHA-256 + Signature algorithm: SHA256withRSA, 2048-bit key + Timestamped by "CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US" on Tue Sep 12 20:08:49 UTC 2017 + Timestamp digest algorithm: SHA-1 + Timestamp signature algorithm: SHA1withRSA, 2048-bit key + +jar verified. + +The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29. +``` + +If the certificate for a signer isn't an X.509 certificate, then there is no +distinguished name information. In that case, just the certificate type and the +alias are shown. For example, if the certificate is a PGP certificate, and the +alias is `bob`, then you would get: `PGP, (bob)`. diff --git a/src/jdk.javadoc/share/man/javadoc.1 b/src/jdk.javadoc/share/man/javadoc.1 deleted file mode 100644 index 4e256a7ce38..00000000000 --- a/src/jdk.javadoc/share/man/javadoc.1 +++ /dev/null @@ -1,1526 +0,0 @@ -.\" Copyright (c) 1994, 2024, 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. -.\" -.\" This code is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -.\" version 2 for more details (a copy is included in the LICENSE file that -.\" accompanied this code). -.\" -.\" You should have received a copy of the GNU General Public License version -.\" 2 along with this work; if not, write to the Free Software Foundation, -.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -.\" -.\" 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.19.2 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[R]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "JAVADOC" "1" "2025" "JDK 24-ea" "JDK Commands" -.hy -.SH NAME -.PP -javadoc - generate HTML pages of API documentation from Java source -files -.SH SYNOPSIS -.PP -\f[V]javadoc\f[R] [\f[I]options\f[R]] [\f[I]packagenames\f[R]] -[\f[I]sourcefiles\f[R]] [\f[V]\[at]\f[R]\f[I]files\f[R]] -.TP -\f[I]options\f[R] -Specifies command-line options, separated by spaces. -See \f[B]Standard \f[VB]javadoc\f[B] Options\f[R], \f[B]Extra -\f[VB]javadoc\f[B] Options\f[R], \f[B]Standard Options for the Standard -Doclet\f[R], and \f[B]Extra Options for the Standard Doclet\f[R]. -.TP -\f[I]packagenames\f[R] -Specifies names of packages that you want to document, separated by -spaces, for example \f[V]java.lang java.lang.reflect java.awt\f[R]. -If you want to also document the subpackages, then use the -\f[V]-subpackages\f[R] option to specify the packages. -.RS -.PP -By default, \f[V]javadoc\f[R] looks for the specified packages in the -current directory and subdirectories. -Use the \f[V]-sourcepath\f[R] option to specify the list of directories -where to look for packages. -.RE -.TP -\f[I]sourcefiles\f[R] -Specifies names of Java source files that you want to document, -separated by spaces, for example -\f[V]Class.java Object.java Button.java\f[R]. -By default, \f[V]javadoc\f[R] looks for the specified classes in the -current directory. -However, you can specify the full path to the class file and use -wildcard characters, for example -\f[V]/home/src/java/awt/Graphics*.java\f[R]. -You can also specify the path relative to the current directory. -.TP -\f[V]\[at]\f[R]\f[I]files\f[R] -Specifies names of files that contain a list of \f[V]javadoc\f[R] tool -options, package names, and source file names in any order. -.SH DESCRIPTION -.PP -The \f[V]javadoc\f[R] tool parses the declarations and documentation -comments in a set of Java source files and produces corresponding HTML -pages that describe (by default) the public and protected classes, -nested and implicitly declared classes (but not anonymous inner -classes), interfaces, constructors, methods, and fields. -You can use the \f[V]javadoc\f[R] tool to generate the API documentation -or the implementation documentation for a set of source files. -.PP -You can run the \f[V]javadoc\f[R] tool on entire packages, individual -source files, or both. -When documenting entire packages, you can use the \f[V]-subpackages\f[R] -option either to recursively traverse a directory and its -subdirectories, or to pass in an explicit list of package names. -When you document individual source files, pass in a list of Java source -file names. -.SS Documentation Comments -.PP -The \f[V]javadoc\f[R] tool uses the documentation comment, if any, that -immediately precedes the beginning of the declaration, whether that is -an annotation, modifier, or the name being declared. -If there are multiple documentation comments before the declaration, -only the last one (closest to the declaration) will be used. -If there are any documentation comments after the beginning of the -declaration, they will be ignored. -To check for any extra or misplaced documentation comments, compile your -source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more -specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. -Within a source file, you may suppress any warnings generated by these -options by using -\f[V]\[at]SuppressWarnings(\[dq]dangling-doc-comments\[dq])\f[R] on a -suitable enclosing declaration. -.SS Conformance -.PP -The standard doclet does not validate the content of documentation -comments for conformance, nor does it attempt to correct any errors in -documentation comments. -Anyone running javadoc is advised to be aware of the problems that may -arise when generating non-conformant output or output containing -executable content, such as JavaScript. -The standard doclet does provide the \f[B]DocLint\f[R] feature to help -developers detect common problems in documentation comments; but it is -also recommended to check the generated output with any appropriate -conformance and other checking tools. -.PP -For more details on the conformance requirements for HTML5 documents, -see \f[B]Conformance requirements for authors\f[R] -[https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors] -in the HTML5 Specification. -For more details on security issues related to web pages, see the -\f[B]Open Web Application Security Project (OWASP)\f[R] -[https://www.owasp.org] page. -.SH OPTIONS -.PP -\f[V]javadoc\f[R] supports command-line options for both the main -\f[V]javadoc\f[R] tool and the currently selected doclet. -The standard doclet is used if no other doclet is specified. -.PP -GNU-style options (that is, those beginning with \f[V]--\f[R]) can use -an equal sign (\f[V]=\f[R]) instead of whitespace characters to separate -the name of an option from its value. -.SS Standard \f[V]javadoc\f[R] Options -.PP -The following core \f[V]javadoc\f[R] options are equivalent to -corresponding \f[V]javac\f[R] options. -See \f[I]Standard Options\f[R] in \f[B]javac\f[R] for the detailed -descriptions of using these options: -.IP \[bu] 2 -\f[V]--add-modules\f[R] -.IP \[bu] 2 -\f[V]-bootclasspath\f[R] -.IP \[bu] 2 -\f[V]--class-path\f[R], \f[V]-classpath\f[R], or \f[V]-cp\f[R] -.IP \[bu] 2 -\f[V]--disable-line-doc-comments\f[R] -.IP \[bu] 2 -\f[V]--enable-preview\f[R] -.IP \[bu] 2 -\f[V]-encoding\f[R] -.IP \[bu] 2 -\f[V]-extdirs\f[R] -.IP \[bu] 2 -\f[V]--limit-modules\f[R] -.IP \[bu] 2 -\f[V]--module\f[R] -.IP \[bu] 2 -\f[V]--module-path\f[R] or \f[V]-p\f[R] -.IP \[bu] 2 -\f[V]--module-source-path\f[R] -.IP \[bu] 2 -\f[V]--release\f[R] -.IP \[bu] 2 -\f[V]--source\f[R] or \f[V]-source\f[R] -.IP \[bu] 2 -\f[V]--source-path\f[R] or \f[V]-sourcepath\f[R] -.IP \[bu] 2 -\f[V]--system\f[R] -.IP \[bu] 2 -\f[V]--upgrade-module-path\f[R] -.PP -The following options are the core \f[V]javadoc\f[R] options that are -not equivalent to a corresponding \f[V]javac\f[R] option: -.TP -\f[V]-breakiterator\f[R] -Computes the first sentence of the description in a documentation -comment using an instance of \f[V]java.text.BreakIterator\f[R] to detect -\f[I]sentence breaks\f[R]. -The rules that are used depend on the \f[B]current locale\f[R]: for -example, for English, a sentence break occurs after a period, question -mark, or exclamation point followed by a space when the next word starts -with a capital letter. -(This is meant to handle most abbreviations, such as \[dq]The serial no. -is valid\[dq], but will not handle \[dq]Mr. -Smith\[dq].) -.RS -.PP -The option is enabled by default if the language of the current locale -is not English. -If the language of the current locale is English, and the -\f[V]-breakiterator\f[R] option is not given, a simple default algorithm -is used, which just looks for a period followed by a space. -.PP -In a traditional \f[V]/**...*/\f[R] comment, the search for the end of -the first sentence is terminated by an HTML block tag, such as -\f[V]

\f[R], \f[V]

\f[R], or the tag for a heading.
-.PP
-In a Markdown \f[V]///\f[R] comment, the search for the end of the first
-sentence skips over any characters enclosed in code spans and links, and
-is terminated by the end of the initial block, as indicated by a blank
-line or the beginning of the next block, such as a list, thematic break,
-or an HTML block.
-.PP
-The first sentence of the description in a documentation comment is used
-in summary tables, index pages, and other situations where a short
-summary is required.
-For more explicit control in any individual documentation comment,
-enclose the contents of the first sentence in a
-\f[V]{\[at]summary ...}\f[R] tag, or when applicable, in a
-\f[V]{\[at]return ...}\f[R] tag.
-.RE
-.TP
-\f[V]-doclet\f[R] \f[I]class\f[R]
-Generates output by using an alternate doclet.
-Use the fully qualified name.
-This doclet defines the content and formats the output.
-If the \f[V]-doclet\f[R] option isn\[aq]t used, then the
-\f[V]javadoc\f[R] tool uses the standard doclet for generating the
-default HTML format.
-This class must implement the \f[V]jdk.javadoc.doclet.Doclet\f[R]
-interface.
-The path to this class is defined by the \f[V]-docletpath\f[R] option.
-.TP
-\f[V]-docletpath\f[R] \f[I]path\f[R]
-Specifies where to find doclet class files (specified with the
-\f[V]-doclet\f[R] option) and any JAR files it depends on.
-If the starting class file is in a JAR file, then this option specifies
-the path to that JAR file.
-You can specify an absolute path or a path relative to the current
-directory.
-If \f[V]path\f[R] contains multiple paths or JAR files, then they should
-be separated with a colon (\f[V]:\f[R]) on Linux and macOS, and a
-semicolon (\f[V];\f[R]) on Windows.
-This option isn\[aq]t necessary when the \f[V]doclet\f[R] starting class
-is already in the search path.
-.TP
-\f[V]-exclude\f[R] \f[I]pkglist\f[R]
-Unconditionally, excludes the specified packages and their subpackages
-from the list formed by \f[V]-subpackages\f[R].
-It excludes those packages even when they would otherwise be included by
-some earlier or later \f[V]-subpackages\f[R] option.
-.RS
-.PP
-The following example would include \f[V]java.io\f[R],
-\f[V]java.util\f[R], and \f[V]java.math\f[R] (among others), but would
-exclude packages rooted at \f[V]java.net\f[R] and \f[V]java.lang\f[R].
-Notice that these examples exclude \f[V]java.lang.ref\f[R], which is a
-subpackage of \f[V]java.lang\f[R].
-Arguments are separated by colons on all operating systems.
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[B]Windows:\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -sourcepath \[rs]user\[rs]src -subpackages java -exclude java.net:java.lang
-\f[R]
-.fi
-.RE
-.RE
-.TP
-\f[V]--expand-requires\f[R] (\f[V]transitive\f[R]|\f[V]all\f[R])
-Instructs the javadoc tool to expand the set of modules to be
-documented.
-By default, only the modules given explicitly on the command line are
-documented.
-Supports the following values:
-.RS
-.IP \[bu] 2
-\f[V]transitive\f[R]: additionally includes all the required transitive
-dependencies of those modules.
-.IP \[bu] 2
-\f[V]all\f[R]: includes all dependencies.
-.RE
-.TP
-\f[V]--help\f[R], \f[V]-help\f[R], \f[V]-h\f[R], or \f[V]-?\f[R]
-Prints a synopsis of the standard options.
-.TP
-\f[V]--help-extra\f[R] or \f[V]-X\f[R]
-Prints a synopsis of the set of extra options.
-.TP
-\f[V]-J\f[R]\f[I]flag\f[R]
-Passes \f[I]flag\f[R] directly to the Java Runtime Environment (JRE)
-that runs the \f[V]javadoc\f[R] tool.
-For example, if you must ensure that the system sets aside 32 MB of
-memory in which to process the generated documentation, then you would
-call the \f[V]-Xmx\f[R] option as follows:
-\f[V]javadoc -J-Xmx32m -J-Xms32m com.mypackage\f[R].
-Be aware that \f[V]-Xms\f[R] is optional because it only sets the size
-of initial memory, which is useful when you know the minimum amount of
-memory required.
-.RS
-.PP
-There is no space between the \f[V]J\f[R] and the \f[V]flag\f[R].
-.PP
-Use the \f[V]-version\f[R] option to report the version of the JRE being
-used to run the \f[V]javadoc\f[R] tool.
-.IP
-.nf
-\f[CB]
-javadoc -J-version
-java version \[dq]17\[dq] 2021-09-14 LTS
-Java(TM) SE Runtime Environment (build 17+35-LTS-2724)
-Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)
-\f[R]
-.fi
-.RE
-.TP
-\f[V]-locale\f[R] \f[I]name\f[R]
-Specifies the locale that the \f[V]javadoc\f[R] tool uses when it
-generates documentation.
-The argument is the name of the locale, as described in
-\f[V]java.util.Locale\f[R] documentation, such as \f[V]en_US\f[R]
-(English, United States) or \f[V]en_US_WIN\f[R] (Windows variant).
-.RS
-.PP
-Specifying a locale causes the \f[V]javadoc\f[R] tool to choose the
-resource files of that locale for messages such as strings in the
-navigation bar, headings for lists and tables, help file contents,
-comments in the \f[V]stylesheet.css\f[R] file, and so on.
-It also specifies the sorting order for lists sorted alphabetically, and
-the sentence separator to determine the end of the first sentence.
-The \f[V]-locale\f[R] option doesn\[aq]t determine the locale of the
-documentation comment text specified in the source files of the
-documented classes.
-.RE
-.TP
-\f[V]-package\f[R]
-Shows only package, protected, and public classes and members.
-.TP
-\f[V]-private\f[R]
-Shows all classes and members.
-.TP
-\f[V]-protected\f[R]
-Shows only protected and public classes and members.
-This is the default.
-.TP
-\f[V]-public\f[R]
-Shows only the public classes and members.
-.TP
-\f[V]-quiet\f[R]
-Shuts off messages so that only the warnings and errors appear to make
-them easier to view.
-It also suppresses the \f[V]version\f[R] string.
-.TP
-\f[V]--show-members\f[R] \f[I]value\f[R]
-Specifies which members (fields, methods, or constructors) are
-documented, where \f[I]value\f[R] can be any of the following:
-.RS
-.IP \[bu] 2
-\f[V]public\f[R] --- shows only public members
-.IP \[bu] 2
-\f[V]protected\f[R] --- shows public and protected members; this is the
-default
-.IP \[bu] 2
-\f[V]package\f[R] --- shows public, protected, and package members
-.IP \[bu] 2
-\f[V]private\f[R] --- shows all members
-.RE
-.TP
-\f[V]--show-module-contents\f[R] \f[I]value\f[R]
-Specifies the documentation granularity of module declarations, where
-\f[I]value\f[R] can be \f[V]api\f[R] or \f[V]all\f[R].
-.TP
-\f[V]--show-packages\f[R] \f[I]value\f[R]
-Specifies which module packages are documented, where \f[I]value\f[R]
-can be \f[V]exported\f[R] or \f[V]all\f[R] packages.
-.TP
-\f[V]--show-types\f[R] \f[I]value\f[R]
-Specifies which types (classes, interfaces, etc.)
-are documented, where \f[I]value\f[R] can be any of the following:
-.RS
-.IP \[bu] 2
-\f[V]public\f[R] --- shows only public types
-.IP \[bu] 2
-\f[V]protected\f[R] --- shows public and protected types; this is the
-default
-.IP \[bu] 2
-\f[V]package\f[R] --- shows public, protected, and package types
-.IP \[bu] 2
-\f[V]private\f[R] --- shows all types
-.RE
-.TP
-\f[V]-subpackages\f[R] \f[I]subpkglist\f[R]
-Generates documentation from source files in the specified packages and
-recursively in their subpackages.
-This option is useful when adding new subpackages to the source code
-because they are automatically included.
-Each package argument is any top-level subpackage (such as
-\f[V]java\f[R]) or fully qualified package (such as
-\f[V]javax.swing\f[R]) that doesn\[aq]t need to contain source files.
-Arguments are separated by colons on all operating systems.
-Wild cards aren\[aq]t allowed.
-Use \f[V]-sourcepath\f[R] to specify where to find the packages.
-This option doesn\[aq]t process source files that are in the source tree
-but don\[aq]t belong to the packages.
-.RS
-.PP
-For example, the following commands generates documentation for packages
-named \f[V]java\f[R] and \f[V]javax.swing\f[R] and all of their
-subpackages.
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[B]Windows:\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -d docs -sourcepath \[rs]user\[rs]src -subpackages java:javax.swing
-\f[R]
-.fi
-.RE
-.RE
-.TP
-\f[V]-verbose\f[R]
-Provides more detailed messages while the \f[V]javadoc\f[R] tool runs.
-Without the \f[V]-verbose\f[R] option, messages appear for loading the
-source files, generating the documentation (one message per source
-file), and sorting.
-The \f[V]-verbose\f[R] option causes the printing of additional messages
-that specify the number of milliseconds to parse each Java source file.
-.TP
-\f[V]--version\f[R]
-Prints version information.
-.TP
-\f[V]-Werror\f[R]
-Reports an error if any warnings occur.
-.PP
-Note that if a Java source file contains an implicitly declared class,
-then that class and its public, protected, and package members will be
-documented regardless of the options such as \f[V]--show-types\f[R],
-\f[V]--show-members\f[R], \f[V]-private\f[R], \f[V]-protected\f[R],
-\f[V]-package\f[R], and \f[V]-public\f[R].
-If \f[V]--show-members\f[R] is specified with value \f[V]private\f[R] or
-if \f[V]-private\f[R] is used then all private members of an implicitly
-declared class will be documented too.
-.SS Extra \f[V]javadoc\f[R] Options
-.PP
-\f[I]Note:\f[R] The additional options for \f[V]javadoc\f[R] are subject
-to change without notice.
-.PP
-The following additional \f[V]javadoc\f[R] options are equivalent to
-corresponding \f[V]javac\f[R] options.
-See \f[I]Extra Options\f[R] in \f[B]javac\f[R] for the detailed
-descriptions of using these options:
-.IP \[bu] 2
-\f[V]--add-exports\f[R]
-.IP \[bu] 2
-\f[V]--add-reads\f[R]
-.IP \[bu] 2
-\f[V]--patch-module\f[R]
-.IP \[bu] 2
-\f[V]-Xmaxerrs\f[R]
-.IP \[bu] 2
-\f[V]-Xmaxwarns\f[R]
-.SS Standard Options for the Standard Doclet
-.PP
-The following options are provided by the standard doclet.
-.TP
-\f[V]--add-script\f[R] \f[I]file\f[R]
-Adds \f[I]file\f[R] as an additional JavaScript file to the generated
-documentation.
-This option can be used one or more times to specify additional script
-files.
-.RS
-.PP
-Command-line example:
-.RS
-.PP
-\f[V]javadoc --add-script first_script.js --add-script second_script.js pkg_foo\f[R]
-.RE
-.RE
-.TP
-\f[V]--add-stylesheet\f[R] \f[I]file\f[R]
-Adds \f[I]file\f[R] as an additional stylesheet file to the generated
-documentation.
-This option can be used one or more times to specify additional
-stylesheets included in the documentation.
-.RS
-.PP
-Command-line example:
-.IP
-.nf
-\f[CB]
-javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo
-\f[R]
-.fi
-.RE
-.TP
-\f[V]--allow-script-in-comments\f[R]
-Allow JavaScript in documentation comments, and options whose value is
-\f[I]html-code\f[R].
-.TP
-\f[V]-author\f[R]
-Includes the text of any \f[V]author\f[R] tags in the generated
-documentation.
-.TP
-\f[V]-bottom\f[R] \f[I]html-code\f[R]
-Specifies the text to be placed at the bottom of each generated page.
-The text can contain HTML tags and white space, but when it does, the
-text must be enclosed in quotation marks.
-Use escape characters for any internal quotation marks within text.
-.TP
-\f[V]-charset\f[R] \f[I]name\f[R]
-Specifies the HTML character set for this document.
-The name should be a preferred MIME name as specified in the \f[B]IANA
-Registry, Character Sets\f[R]
-[http://www.iana.org/assignments/character-sets].
-.RS
-.PP
-For example:
-.IP
-.nf
-\f[CB]
-javadoc -charset \[dq]iso-8859-1\[dq] mypackage
-\f[R]
-.fi
-.PP
-This command inserts the following line, containing a
-\f[B]\f[VB]meta\f[B] element\f[R]
-[https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element]
-in the head of every generated page:
-.IP
-.nf
-\f[CB]
-
-\f[R]
-.fi
-.RE
-.TP
-\f[V]-d\f[R] \f[I]directory\f[R]
-Specifies the destination directory where the \f[V]javadoc\f[R] tool
-saves the generated HTML files.
-If you omit the \f[V]-d\f[R] option, then the files are saved to the
-current directory.
-The \f[V]directory\f[R] value can be absolute or relative to the current
-working directory.
-The destination directory is automatically created when the
-\f[V]javadoc\f[R] tool runs.
-.RS
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R] For example, the following command generates
-the documentation for the package \f[V]com.mypackage\f[R] and saves the
-results in the \f[V]/user/doc/\f[R] directory:
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -d /user/doc/ com.mypackage
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[B]Windows:\f[R] For example, the following command generates the
-documentation for the package \f[V]com.mypackage\f[R] and saves the
-results in the \f[V]\[rs]user\[rs]doc\[rs]\f[R] directory:
-.RS 2
-.IP
-.nf
-\f[CB]
-javadoc -d \[rs]user\[rs]doc\[rs] com.mypackage
-\f[R]
-.fi
-.RE
-.RE
-.TP
-\f[V]-docencoding\f[R] \f[I]name\f[R]
-Specifies the encoding of the generated HTML files.
-The name should be a preferred MIME name as specified in the \f[B]IANA
-Registry, Character Sets\f[R]
-[http://www.iana.org/assignments/character-sets].
-.RS
-.PP
-Three options are available for use in a \f[V]javadoc\f[R] encoding
-command.
-The \f[V]-encoding\f[R] option is used for encoding the files read by
-the \f[V]javadoc\f[R] tool, while the \f[V]-docencoding\f[R] and
-\f[V]-charset\f[R] options are used for encoding the files written by
-the tool.
-Of the three available options, at most, only the input and an output
-encoding option are used in a single encoding command.
-If you specify both input and output encoding options in a command, they
-must be the same value.
-If you specify neither output option, it defaults to the input encoding.
-.PP
-For example:
-.IP
-.nf
-\f[CB]
-javadoc -docencoding \[dq]iso-8859-1\[dq] mypackage
-\f[R]
-.fi
-.RE
-.TP
-\f[V]-docfilessubdirs\f[R]
-Enables deep copying of \f[V]doc-files\f[R] directories.
-Subdirectories and all contents are recursively copied to the
-destination.
-For example, the directory \f[V]doc-files/example/images\f[R] and all of
-its contents are copied.
-Use the \f[B]\f[VB]-excludedocfilessubdir\f[B]\f[R] option to restrict
-the subdirectories to be copied.
-.TP
-\f[V]-doctitle\f[R] \f[I]html-code\f[R]
-Specifies the title to place near the top of the overview summary file.
-The text specified in the \f[V]title\f[R] tag is placed as a centered,
-level-one heading directly beneath the navigation bar.
-The \f[V]title\f[R] tag can contain HTML tags and white space, but when
-it does, you must enclose the title in quotation marks.
-Additional quotation marks within the \f[V]title\f[R] tag must be
-escaped.
-For example,
-\f[V]javadoc -doctitle \[dq]My Library
v1.0\[dq] com.mypackage\f[R].
-.TP
-\f[V]-excludedocfilessubdir\f[R] \f[I]name1\f[R]\f[V],\f[R]\f[I]name2...\f[R]
-Excludes any subdirectories with the given names when recursively
-copying \f[V]doc-files\f[R] subdirectories.
-See \f[B]\f[VB]-docfilessubdirs\f[B]\f[R].
-For historical reasons, \f[V]:\f[R] can be used anywhere in the argument
-as a separator instead of \f[V],\f[R].
-.TP
-\f[V]-footer\f[R] \f[I]html-code\f[R]
-This option is no longer supported and reports a warning.
-.TP
-\f[V]-group\f[R] \f[I]name\f[R] \f[I]p1\f[R]\f[V],\f[R]\f[I]p2...\f[R]
-Group the specified packages together in the Overview page.
-For historical reasons, \f[V]:\f[R] can be used as a separator anywhere
-in the argument instead of \f[V],\f[R].
-.TP
-\f[V]-header\f[R] \f[I]html-code\f[R]
-Specifies the header text to be placed at the top of each output file.
-The header is placed to the right of the navigation bar.
-The \f[V]header\f[R] can contain HTML tags and white space, but when it
-does, the \f[V]header\f[R] must be enclosed in quotation marks.
-Use escape characters for internal quotation marks within a header.
-For example,
-\f[V]javadoc -header \[dq]My Library
v1.0\[dq] com.mypackage\f[R].
-.TP
-\f[V]-helpfile\f[R] \f[I]filename\f[R]
-Specifies a file containing the text that will be displayed when the
-\f[B]HELP\f[R] link in the navigation bar is clicked.
-If this option is not given, the \f[V]javadoc\f[R] tool creates a
-default page that will be used.
-.TP
-\f[V]-html5\f[R]
-This option is a no-op and is just retained for backwards compatibility.
-.TP
-\f[V]--javafx\f[R] or \f[V]-javafx\f[R]
-Enables JavaFX functionality.
-This option is enabled by default if the JavaFX library classes are
-detected on the module path.
-.TP
-\f[V]-keywords\f[R]
-Adds HTML keyword \f[V]\f[R] tags to the generated file for each
-class.
-These tags can help search engines that look for \f[V]\f[R] tags
-find the pages.
-Most search engines that search the entire Internet don\[aq]t look at
-\f[V]\f[R] tags, because pages can misuse them.
-Search engines offered by companies that confine their searches to their
-own website can benefit by looking at \f[V]\f[R] tags.
-The \f[V]\f[R] tags include the fully qualified name of the class
-and the unqualified names of the fields and methods.
-Constructors aren\[aq]t included because they are identical to the class
-name.
-For example, the page for the class \f[V]String\f[R] includes these
-keywords:
-.RS
-.IP
-.nf
-\f[CB]
-
-
-
-
-\f[R]
-.fi
-.RE
-.TP
-\f[V]-link\f[R] \f[I]url\f[R]
-Creates links to existing \f[V]javadoc\f[R] generated documentation of
-externally referenced classes.
-The \f[I]url\f[R] argument is the absolute or relative URL of the
-directory that contains the external \f[V]javadoc\f[R] generated
-documentation.
-You can specify multiple \f[V]-link\f[R] options in a specified
-\f[V]javadoc\f[R] tool run to link to multiple documents.
-.RS
-.PP
-Either a \f[V]package-list\f[R] or an \f[V]element-list\f[R] file must
-be in this \f[I]url\f[R] directory (otherwise, use the
-\f[V]-linkoffline\f[R] option).
-.PP
-\f[I]Note:\f[R] The \f[V]package-list\f[R] and \f[V]element-list\f[R]
-files are generated by the \f[V]javadoc\f[R] tool when generating the
-API documentation and should not be modified by the user.
-.PP
-When you use the \f[V]javadoc\f[R] tool to document packages, it uses
-the \f[V]package-list\f[R] file to determine the packages declared in an
-API.
-When you generate API documents for modules, the \f[V]javadoc\f[R] tool
-uses the \f[V]element-list\f[R] file to determine the modules and
-packages declared in an API.
-.PP
-The \f[V]javadoc\f[R] tool reads the names from the appropriate list
-file and then links to the packages or modules at that URL.
-.PP
-When the \f[V]javadoc\f[R] tool runs, the \f[I]url\f[R] value is copied
-into the \f[V]\f[R] links that are created.
-Therefore, \f[I]url\f[R] must be the URL to the directory and not to a
-file.
-.PP
-You can use an absolute link for \f[I]url\f[R] to enable your documents
-to link to a document on any web site, or you can use a relative link to
-link only to a relative location.
-If you use a relative link, then the value you pass in should be the
-relative path from the destination directory (specified with the
-\f[V]-d\f[R] option) to the directory containing the packages being
-linked to.
-When you specify an absolute link, you usually use an HTTP link.
-However, if you want to link to a file system that has no web server,
-then you can use a file link.
-Use a file link only when everyone who wants to access the generated
-documentation shares the same file system.
-In all cases, and on all operating systems, use a slash as the
-separator, whether the URL is absolute or relative, and
-\f[V]https:\f[R], \f[V]http:\f[R], or \f[V]file:\f[R] as specified in
-the \f[B]RFC 1738: Uniform Resource Locators (URL)\f[R]
-[https://www.rfc-editor.org/info/rfc1738].
-.IP
-.nf
-\f[CB]
--link https://///.../
--link http://///.../
--link file://///.../
--link //.../
-\f[R]
-.fi
-.RE
-.TP
-\f[V]--link-modularity-mismatch\f[R] (\f[V]warn\f[R]|\f[V]info\f[R])
-Specifies whether external documentation with wrong modularity (e.g.
-non-modular documentation for a modular library, or the reverse case)
-should be reported as a warning (\f[V]warn\f[R]) or just a message
-(\f[V]info\f[R]).
-The default behavior is to report a warning.
-.TP
-\f[V]-linkoffline\f[R] \f[I]url1\f[R] \f[I]url2\f[R]
-This option is a variation of the \f[V]-link\f[R] option.
-They both create links to \f[V]javadoc\f[R] generated documentation for
-externally referenced classes.
-You can specify multiple \f[V]-linkoffline\f[R] options in a specified
-\f[V]javadoc\f[R] tool run.
-.RS
-.PP
-Use the \f[V]-linkoffline\f[R] option when:
-.IP \[bu] 2
-Linking to a document on the web that the \f[V]javadoc\f[R] tool
-can\[aq]t access through a web connection
-.IP \[bu] 2
-The \f[V]package-list\f[R] or \f[V]element-list\f[R] file of the
-external document either isn\[aq]t accessible or doesn\[aq]t exist at
-the URL location, but does exist at a different location and can be
-specified by either the \f[V]package-list\f[R] or \f[V]element-list\f[R]
-file (typically local).
-.PP
-\f[I]Note:\f[R] The \f[V]package-list\f[R] and \f[V]element-list\f[R]
-files are generated by the \f[V]javadoc\f[R] tool when generating the
-API documentation and should not be modified by the user.
-.PP
-If \f[I]url1\f[R] is accessible only on the World Wide Web, then the
-\f[V]-linkoffline\f[R] option removes the constraint that the
-\f[V]javadoc\f[R] tool must have a web connection to generate
-documentation.
-.PP
-Another use of the \f[V]-linkoffline\f[R] option is as a work-around to
-update documents.
-After you have run the \f[V]javadoc\f[R] tool on a full set of packages
-or modules, you can run the \f[V]javadoc\f[R] tool again on a smaller
-set of changed packages or modules, so that the updated files can be
-inserted back into the original set.
-.PP
-For example, the \f[V]-linkoffline\f[R] option takes two arguments.
-The first is for the string to be embedded in the \f[V]\f[R]
-links, and the second tells the \f[V]javadoc\f[R] tool where to find
-either the \f[V]package-list\f[R] or \f[V]element-list\f[R] file.
-.PP
-The \f[I]url1\f[R] or \f[I]url2\f[R] value is the absolute or relative
-URL of the directory that contains the external \f[V]javadoc\f[R]
-generated documentation that you want to link to.
-When relative, the value should be the relative path from the
-destination directory (specified with the \f[V]-d\f[R] option) to the
-root of the packages being linked to.
-See \f[I]url\f[R] in the \f[V]-link\f[R] option.
-.RE
-.TP
-\f[V]--link-platform-properties\f[R] \f[I]url\f[R]
-Specifies a properties file used to configure links to platform
-documentation.
-.RS
-.PP
-The \f[I]url\f[R] argument is expected to point to a properties file
-containing one or more entries with the following format, where
-\f[V]\f[R] is the platform version as passed to the
-\f[V]--release\f[R] or \f[V]--source\f[R] option and \f[V]\f[R] is
-the base URL of the corresponding platform API documentation:
-.IP
-.nf
-\f[CB]
-doclet.platform.docs.=
-\f[R]
-.fi
-.PP
-For instance, a properties file containing URLs for releases 15 to 17
-might contain the following lines:
-.IP
-.nf
-\f[CB]
-doclet.platform.docs.15=https://example.com/api/15/
-doclet.platform.docs.16=https://example.com/api/16/
-doclet.platform.docs.17=https://example.com/api/17/
-\f[R]
-.fi
-.PP
-If the properties file does not contain an entry for a particular
-release no platform links are generated.
-.RE
-.TP
-\f[V]-linksource\f[R]
-Creates an HTML version of each source file (with line numbers) and adds
-links to them from the standard HTML documentation.
-Links are created for classes, interfaces, constructors, methods, and
-fields whose declarations are in a source file.
-Otherwise, links aren\[aq]t created, such as for default constructors
-and generated classes.
-.RS
-.PP
-This option exposes all private implementation details in the included
-source files, including private classes, private fields, and the bodies
-of private methods, regardless of the \f[V]-public\f[R],
-\f[V]-package\f[R], \f[V]-protected\f[R], and \f[V]-private\f[R]
-options.
-Unless you also use the \f[V]-private\f[R] option, not all private
-classes or interfaces are accessible through links.
-.PP
-Each link appears on the name of the identifier in its declaration.
-For example, the link to the source code of the \f[V]Button\f[R] class
-would be on the word \f[V]Button\f[R]:
-.IP
-.nf
-\f[CB]
-public class Button extends Component implements Accessible
-\f[R]
-.fi
-.PP
-The link to the source code of the \f[V]getLabel\f[R] method in the
-\f[V]Button\f[R] class is on the word \f[V]getLabel\f[R]:
-.IP
-.nf
-\f[CB]
-public String getLabel()
-\f[R]
-.fi
-.RE
-.TP
-\f[V]--main-stylesheet\f[R] \f[I]file\f[R] or \f[V]-stylesheetfile\f[R] \f[I]file\f[R]
-Specifies the path of an alternate stylesheet file that contains the
-definitions for the CSS styles used in the generated documentation.
-This option lets you override the default.
-If you do not specify the option, the \f[V]javadoc\f[R] tool will create
-and use a default stylesheet.
-The file name can be any name and isn\[aq]t restricted to
-\f[V]stylesheet.css\f[R].
-The \f[V]--main-stylesheet\f[R] option is the preferred form.
-.RS
-.PP
-Command-line example:
-.IP
-.nf
-\f[CB]
-javadoc --main-stylesheet main_stylesheet.css pkg_foo
-\f[R]
-.fi
-.RE
-.TP
-\f[V]-nocomment\f[R]
-Suppresses the entire comment body, including the main description and
-all tags, and generate only declarations.
-This option lets you reuse source files that were originally intended
-for a different purpose so that you can produce skeleton HTML
-documentation during the early stages of a new project.
-.TP
-\f[V]-nodeprecated\f[R]
-Prevents the generation of any deprecated API in the documentation.
-This does what the \f[V]-nodeprecatedlist\f[R] option does, and it
-doesn\[aq]t generate any deprecated API throughout the rest of the
-documentation.
-This is useful when writing code when you don\[aq]t want to be
-distracted by the deprecated code.
-.TP
-\f[V]-nodeprecatedlist\f[R]
-Prevents the generation of the file that contains the list of deprecated
-APIs (\f[V]deprecated-list.html\f[R]) and the link in the navigation bar
-to that page.
-The \f[V]javadoc\f[R] tool continues to generate the deprecated API
-throughout the rest of the document.
-This is useful when your source code contains no deprecated APIs, and
-you want to make the navigation bar cleaner.
-.TP
-\f[V]--no-fonts\f[R]
-Prevents inclusion of font files in the generated documentation.
-This can be useful if the documentation uses a custom stylesheet which
-does not use the default fonts.
-.TP
-\f[V]-nohelp\f[R]
-Omits the \f[B]HELP\f[R] link in the navigation bar at the top of each
-generated page.
-.TP
-\f[V]-noindex\f[R]
-Omits the index from the generated documents.
-The index is produced by default.
-.TP
-\f[V]-nonavbar\f[R]
-Prevents the generation of the navigation bar and header.
-The \f[V]-nonavbar\f[R] option has no effect on the \f[V]-bottom\f[R]
-option.
-The \f[V]-nonavbar\f[R] option is useful when you are interested only in
-the content and have no need for navigation, such as when you are
-converting the files to PostScript or PDF for printing only.
-.TP
-\f[V]--no-platform-links\f[R]
-Prevents the generation of links to platform documentation.
-These links are generated by default.
-.TP
-\f[V]-noqualifier\f[R] \f[I]name1\f[R]\f[V],\f[R]\f[I]name2...\f[R]
-Excludes the list of qualifiers from the output.
-The package name is removed from places where class or interface names
-appear.
-For historical reasons, \f[V]:\f[R] can be used anywhere in the argument
-as a separator instead of \f[V],\f[R].
-.RS
-.PP
-The following example omits all package qualifiers:
-\f[V]-noqualifier all\f[R].
-.PP
-The following example omits \f[V]java.lang\f[R] and \f[V]java.io\f[R]
-package qualifiers: \f[V]-noqualifier java.lang:java.io\f[R].
-.PP
-The following example omits package qualifiers starting with
-\f[V]java\f[R] and \f[V]com.sun\f[R] subpackages, but not
-\f[V]javax: -noqualifier java.*:com.sun.*\f[R].
-.PP
-Where a package qualifier would appear due to the previous behavior, the
-name can be suitably shortened.
-This rule is in effect whether or not the \f[V]-noqualifier\f[R] option
-is used.
-.RE
-.TP
-\f[V]-nosince\f[R]
-Omits from the generated documentation the \f[V]Since\f[R] sections
-derived from any \f[V]since\f[R] tags.
-.TP
-\f[V]-notimestamp\f[R]
-Suppresses the time stamp, which is hidden in an HTML comment in the
-generated HTML near the top of each page.
-The \f[V]-notimestamp\f[R] option is useful when you want to run the
-\f[V]javadoc\f[R] tool on two source bases and compare them, because it
-prevents time stamps from causing a difference (which would otherwise be
-a difference on every page).
-The time stamp includes the \f[V]javadoc\f[R] tool release number.
-.TP
-\f[V]-notree\f[R]
-Omits the class and interface hierarchy pages from the generated
-documents.
-These are the pages you reach using the \f[B]TREE\f[R] link in the
-navigation bar.
-The hierarchy is produced by default.
-.TP
-\f[V]--override-methods\f[R] (\f[V]detail\f[R]|\f[V]summary\f[R])
-Documents overridden methods in the detail or summary sections.
-The default is \f[V]detail\f[R].
-.TP
-\f[V]-overview\f[R] \f[I]filename\f[R]
-Specifies that the \f[V]javadoc\f[R] tool should retrieve the content
-for the overview documentation from the file specified by
-\f[I]filename\f[R] and place it on the Overview page
-(\f[V]overview-summary.html\f[R]).
-If the \f[I]filename\f[R] is a relative path, it is evaluated relative
-to the current working directory.
-.RS
-.PP
-The file may be an HTML file, with a filename ending in \f[V].html\f[R],
-or a Markdown file, with a filename ending in \f[V].md\f[R].
-If the file is an HTML file, the content for the overview documentation
-is taken from the \f[V]
\f[R] element in the file, if one is
-present, or from the \f[V]\f[R] element is there is no
-\f[V]
\f[R] element.
-If the file is a Markdown file, the entire content of the file is used.
-.PP
-The title on the overview page is set by \f[V]-doctitle\f[R].
-.PP
-\f[I]Note:\f[R] older versions of the \f[V]javadoc\f[R] tool assumed
-that any use of this option was for an HTML file, and allowed any
-extension for the \f[I]filename\f[R].
-.RE
-.TP
-\f[V]-serialwarn\f[R]
-Reports compile-time warnings for missing \f[V]\[at]serial\f[R] tags.
-By default, Javadoc reports no serial warnings.
-Use this option to display the serial warnings, which helps to properly
-document default serializable fields and \f[V]writeExternal\f[R]
-methods.
-.TP
-\f[V]--since\f[R] \f[I]release\f[R](\f[V],\f[R]\f[I]release\f[R])*
-Generates documentation for APIs that were added or newly deprecated in
-the specified \f[I]release\f[R]s.
-.RS
-.PP
-If the \f[V]\[at]since\f[R] tag in the \f[V]javadoc\f[R] comment of an
-element in the documented source code matches a \f[I]release\f[R] passed
-as the option argument, information about the element and the release it
-was added in is included in a \[dq]New API\[dq] page.
-.PP
-If the \[dq]Deprecated API\[dq] page is generated and the
-\f[V]since\f[R] element of the \f[V]java.lang.Deprecated\f[R] annotation
-of a documented element matches a \f[I]release\f[R] in the option
-arguments, information about the release the element was deprecated in
-is added to the \[dq]Deprecated API\[dq] page.
-.PP
-Releases are compared using case-sensitive string comparison.
-.RE
-.TP
-\f[V]--since-label\f[R] \f[I]text\f[R]
-Specifies the \f[I]text\f[R] to use in the heading of the \[dq]New
-API\[dq] page.
-This may contain information about the releases covered in the page,
-e.g.
-\[dq]New API in release 2.0\[dq], or \[dq]New API since release 1\[dq].
-.TP
-\f[V]--snippet-path\f[R] \f[I]snippetpathlist\f[R]
-Specifies the search paths for finding files for external snippets.
-The \f[I]snippetpathlist\f[R] can contain multiple paths by separating
-them with the platform path separator (\f[V];\f[R] on Windows;
-\f[V]:\f[R] on other platforms.)
-The standard doclet first searches the \f[V]snippet-files\f[R]
-subdirectory in the package containing the snippet, and then searches
-all the directories in the given list.
-.TP
-\f[V]-sourcetab\f[R] \f[I]tab-length\f[R]
-Specifies the number of spaces each tab uses in the source.
-.TP
-\f[V]--spec-base-url\f[R] \f[I]url\f[R]
-Specifies the base URL for relative URLs in \f[V]\[at]spec\f[R] tags, to
-be used when generating links to any external specifications.
-It can either be an absolute URL, or a relative URL, in which case it is
-evaluated relative to the base directory of the generated output files.
-The default value is equivalent to \f[V]{\[at]docRoot}/../specs\f[R].
-.TP
-\f[V]-splitindex\f[R]
-Splits the index file into multiple files, alphabetically, one file per
-letter, plus a file for any index entries that start with
-non-alphabetical symbols.
-.TP
-\f[V]-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
-Specifies a custom tag with a single argument.
-For the \f[V]javadoc\f[R] tool to spell-check tag names, it is important
-to include a \f[V]-tag\f[R] option for every custom tag that is present
-in the source code, disabling (with \f[V]X\f[R]) those that aren\[aq]t
-being output in the current run.
-The colon (\f[V]:\f[R]) is always the separator.
-To include a colon in the tag name, escape it with a backward slash
-(\f[V]\[rs]\f[R]).
-The \f[V]-tag\f[R] option outputs the tag heading, \f[I]header\f[R], in
-bold, followed on the next line by the text from its single argument.
-Similar to any block tag, the argument text can contain inline tags,
-which are also interpreted.
-The output is similar to standard one-argument tags, such as the
-\f[V]\[at]return\f[R] and \f[V]\[at]author\f[R] tags.
-Omitting a \f[I]header\f[R] value causes the \f[I]name\f[R] to be the
-heading.
-\f[I]locations\f[R] is a list of characters specifying the kinds of
-declarations in which the tag may be used.
-The following characters may be used, in either uppercase or lowercase:
-.RS
-.IP \[bu] 2
-\f[V]A\f[R]: all declarations
-.IP \[bu] 2
-\f[V]C\f[R]: constructors
-.IP \[bu] 2
-\f[V]F\f[R]: fields
-.IP \[bu] 2
-\f[V]M\f[R]: methods
-.IP \[bu] 2
-\f[V]O\f[R]: the overview page and other documentation files in
-\f[V]doc-files\f[R] subdirectories
-.IP \[bu] 2
-\f[V]P\f[R]: packages
-.IP \[bu] 2
-\f[V]S\f[R]: modules
-.IP \[bu] 2
-\f[V]T\f[R]: types (classes and interfaces)
-.IP \[bu] 2
-\f[V]X\f[R]: nowhere: the tag is disabled, and will be ignored
-.PP
-The order in which tags are given on the command line will be used as
-the order in which the tags appear in the generated output.
-You can include standard tags in the order given on the command line by
-using the \f[V]-tag\f[R] option with no \f[I]locations\f[R] or
-\f[I]header\f[R].
-.RE
-.TP
-\f[V]-taglet\f[R] \f[I]class\f[R]
-Specifies the fully qualified name of the taglet used in generating the
-documentation for that tag.
-Use the fully qualified name for the \f[I]class\f[R] value.
-This taglet also defines the number of text arguments that the custom
-tag has.
-The taglet accepts those arguments, processes them, and generates the
-output.
-.RS
-.PP
-Taglets are useful for block or inline tags.
-They can have any number of arguments and implement custom behavior,
-such as making text bold, formatting bullets, writing out the text to a
-file, or starting other processes.
-Taglets can only determine where a tag should appear and in what form.
-All other decisions are made by the doclet.
-A taglet can\[aq]t do things such as remove a class name from the list
-of included classes.
-However, it can execute side effects, such as printing the tag\[aq]s
-text to a file or triggering another process.
-Use the \f[V]-tagletpath\f[R] option to specify the path to the taglet.
-The following example inserts the To Do taglet after Parameters and
-ahead of Throws in the generated pages.
-.IP
-.nf
-\f[CB]
--taglet com.sun.tools.doclets.ToDoTaglet
--tagletpath /home/taglets
--tag return
--tag param
--tag todo
--tag throws
--tag see
-\f[R]
-.fi
-.PP
-Alternately, you can use the \f[V]-taglet\f[R] option in place of its
-\f[V]-tag\f[R] option, but that might be difficult to read.
-.RE
-.TP
-\f[V]-tagletpath\f[R] \f[I]tagletpathlist\f[R]
-Specifies the search paths for finding taglet class files.
-The \f[I]tagletpathlist\f[R] can contain multiple paths by separating
-them with the platform path separator (\f[V];\f[R] on Windows;
-\f[V]:\f[R] on other platforms.)
-The \f[V]javadoc\f[R] tool searches all subdirectories of the specified
-paths.
-.TP
-\f[V]-top\f[R] \f[I]html-code\f[R]
-Specifies the text to be placed at the top of each output file.
-.TP
-\f[V]-use\f[R]
-Creates class and package usage pages.
-Includes one Use page for each documented class and package.
-The page describes what packages, classes, methods, constructors, and
-fields use any API of the specified class or package.
-Given class C, things that use class C would include subclasses of C,
-fields declared as C, methods that return C, and methods and
-constructors with parameters of type C.
-For example, you can look at the Use page for the \f[V]String\f[R] type.
-Because the \f[V]getName\f[R] method in the \f[V]java.awt.Font\f[R]
-class returns type \f[V]String\f[R], the \f[V]getName\f[R] method uses
-\f[V]String\f[R] and so the \f[V]getName\f[R] method appears on the Use
-page for \f[V]String\f[R].
-This documents only uses of the API, not the implementation.
-When a method uses \f[V]String\f[R] in its implementation, but
-doesn\[aq]t take a string as an argument or return a string, that
-isn\[aq]t considered a use of \f[V]String\f[R].
-To access the generated Use page, go to the class or package and click
-the \f[B]USE\f[R] link in the navigation bar.
-.TP
-\f[V]-version\f[R]
-Includes the text of any \f[V]version\f[R] tags in the generated
-documentation.
-This text is omitted by default.
-Note: To find out what version of the \f[V]javadoc\f[R] tool you are
-using, use the \f[V]--version\f[R] option (with two hyphens).
-.TP
-\f[V]-windowtitle\f[R] \f[I]title\f[R]
-Specifies the title to be placed in the HTML \f[V]\f[R] tag.
-The text specified in the \f[V]title\f[R] tag appears in the window
-title and in any browser bookmarks (favorite places) that someone
-creates for this page.
-This title should not contain any HTML tags because a browser will not
-interpret them correctly.
-Use escape characters on any internal quotation marks within the
-\f[V]title\f[R] tag.
-If the \f[V]-windowtitle\f[R] option is omitted, then the
-\f[V]javadoc\f[R] tool uses the value of the \f[V]-doctitle\f[R] option
-for the \f[V]-windowtitle\f[R] option.
-For example,
-\f[V]javadoc -windowtitle \[dq]My Library\[dq] com.mypackage\f[R].
-.SS Extra Options for the Standard Doclet
-.PP
-The following are additional options provided by the standard doclet and
-are subject to change without notice.
-Additional options are less commonly used or are otherwise regarded as
-advanced.
-.TP
-\f[V]--date\f[R] \f[I]date-and-time\f[R]
-Specifies the value to be used to timestamp the generated pages, in
-\f[B]ISO 8601\f[R]
-[https://www.iso.org/iso-8601-date-and-time-format.html] format.
-The specified value must be within 10 years of the current date and
-time.
-It is an error to specify both \f[V]-notimestamp\f[R] and
-\f[V]--date\f[R].
-Using a specific value means the generated documentation can be part of
-a \f[B]reproducible build\f[R] [https://reproducible-builds.org/].
-If the option is not given, the default value is the current date and
-time.
-For example:
-.RS
-.IP
-.nf
-\f[CB]
-javadoc --date 2022-02-01T17:41:59-08:00 mypackage
-\f[R]
-.fi
-.RE
-.TP
-\f[V]--legal-notices\f[R] (\f[V]default\f[R]|\f[V]none\f[R]|\f[I]directory\f[R])
-Specifies the location from which to copy legal files to the generated
-documentation.
-If the option is not specified or is used with the value
-\f[V]default\f[R], the files are copied from the default location.
-If the argument is used with value \f[V]none\f[R], no files are copied.
-Every other argument is interpreted as directory from which to copy the
-legal files.
-.TP
-\f[V]--no-frames\f[R]
-This option is no longer supported and reports a warning.
-.TP
-\f[V]-Xdoclint\f[R]
-Enables recommended checks for problems in documentation comments.
-.RS
-.PP
-By default, the \f[V]-Xdoclint\f[R] option is enabled.
-Disable it with the option \f[V]-Xdoclint:none\f[R].
-.PP
-For more details, see \f[B]DocLint\f[R].
-.RE
-.TP
-\f[V]-Xdoclint:\f[R]\f[I]flag\f[R],\f[I]flag\f[R],...
-Enables or disables specific checks for different kinds of issues in
-documentation comments.
-.RS
-.PP
-Each \f[I]flag\f[R] can be one of \f[V]all\f[R], \f[V]none\f[R], or
-\f[V][-]\f[R]\f[I]group\f[R] where \f[I]group\f[R] has one of the
-following values: \f[V]accessibility\f[R], \f[V]html\f[R],
-\f[V]missing\f[R], \f[V]reference\f[R], \f[V]syntax\f[R].
-For more details on these values, see \f[B]DocLint Groups\f[R].
-.PP
-When specifying two or more flags, you can either use a single
-\f[V]-Xdoclint:...\f[R] option, listing all the desired flags, or you
-can use multiple options giving one or more flag in each option.
-For example, use either of the following commands to check for the HTML,
-syntax, and accessibility issues in the file \f[V]MyFile.java\f[R].
-.IP
-.nf
-\f[CB]
-javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility MyFile.java
-javadoc -Xdoclint:html,syntax,accessibility MyFile.java
-\f[R]
-.fi
-.PP
-The following examples illustrate how to change what DocLint reports:
-.IP \[bu] 2
-\f[V]-Xdoclint:none\f[R] --- disables all checks
-.IP \[bu] 2
-\f[V]-Xdoclint:\f[R]\f[I]group\f[R] --- enables \f[I]group\f[R] checks
-.IP \[bu] 2
-\f[V]-Xdoclint:all\f[R] --- enables all groups of checks
-.IP \[bu] 2
-\f[V]-Xdoclint:all,-\f[R]\f[I]group\f[R] --- enables all checks except
-\f[I]group\f[R] checks
-.PP
-For more details, see \f[B]DocLint\f[R].
-.RE
-.TP
-\f[V]-Xdoclint/package:\f[R][\f[V]-\f[R]]\f[I]packages\f[R]
-Enables or disables checks in specific packages.
-\f[I]packages\f[R] is a comma separated list of package specifiers.
-A package specifier is either a qualified name of a package or a package
-name prefix followed by \f[V]*\f[R], which expands to all subpackages of
-the given package.
-Prefix the package specifier with \f[V]-\f[R] to disable checks for the
-specified packages.
-.RS
-.PP
-For more details, see \f[B]DocLint\f[R].
-.RE
-.TP
-\f[V]-Xdocrootparent\f[R] \f[I]url\f[R]
-Replaces all \f[V]\[at]docRoot\f[R] items followed by \f[V]/..\f[R] in
-documentation comments with \f[I]url\f[R].
-.SH DOCLINT
-.PP
-DocLint provides the ability to check for possible problems in
-documentation comments.
-Problems may be reported as warnings or errors, depending on their
-severity.
-For example, a missing comment may be bad style that deserves a warning,
-but a link to an unknown Java declaration is more serious and deserves
-an error.
-Problems are organized into \f[B]groups\f[R], and options can be used to
-enable or disable messages in one or more groups.
-Within the source code, messages in one or more groups can be
-\f[B]suppressed\f[R] by using \f[V]\[at]SuppressWarnings\f[R]
-annotations.
-.PP
-When invoked from \f[V]javadoc\f[R], by default DocLint checks all
-comments that are used in the generated documentation.
-It thus relies on other command-line options to determine which
-declarations, and which corresponding documentation comments will be
-included.
-\f[I]Note:\f[R] this may mean that even comments on some private members
-of serializable classes will also be checked, if the members need to be
-documented in the generated \f[V]Serialized Forms\f[R] page.
-.PP
-In contrast, when DocLint is invoked from \f[V]javac\f[R], DocLint
-solely relies on the various \f[V]-Xdoclint...\f[R] options to determine
-which documentation comments to check.
-.PP
-DocLint doesn\[aq]t attempt to fix invalid input, it just reports it.
-.PP
-\f[I]Note:\f[R] DocLint doesn\[aq]t guarantee the completeness of these
-checks.
-In particular, it isn\[aq]t a full HTML compliance checker.
-The goal is to just report common errors in a convenient manner.
-.SS Groups
-.PP
-The checks performed by DocLint are organized into groups.
-The warnings and errors in each group can be enabled or disabled with
-command-line options, or suppressed with \f[V]\[at]SuppressWarnings\f[R]
-annotations.
-.PP
-The groups are as follows:
-.IP \[bu] 2
-\f[V]accessibility\f[R] --- Checks for issues related to accessibility.
-For example, no \f[V]alt\f[R] attribute specified in an \f[V]<img>\f[R]
-element, or no caption or summary attributes specified in a
-\f[V]<table>\f[R] element.
-.RS 2
-.PP
-Issues are reported as errors if a downstream validation tool might be
-expected to report an error in the files generated by \f[V]javadoc\f[R].
-.PP
-For reference, see the \f[B]Web Content Accessibility Guidelines\f[R]
-[https://www.w3.org/WAI/standards-guidelines/wcag/].
-.RE
-.IP \[bu] 2
-\f[V]html\f[R] --- Detects common high-level HTML issues.
-For example, putting block elements inside inline elements, or not
-closing elements that require an end tag.
-.RS 2
-.PP
-Issues are reported as errors if a downstream validation tool might be
-expected to report an error in the files generated by \f[V]javadoc\f[R].
-.PP
-For reference, see the \f[B]HTML Living Standard\f[R]
-[https://html.spec.whatwg.org/multipage/].
-.RE
-.IP \[bu] 2
-\f[V]missing\f[R] --- Checks for missing documentation comments or tags.
-For example, a missing comment on a class declaration, or a missing
-\f[V]\[at]param\f[R] or \f[V]\[at]return\f[R] tag in the comment for a
-method declaration.
-.RS 2
-.PP
-Issues related to missing items are typically reported as warnings
-because they are unlikely to be reported as errors by downstream
-validation tools that may be used to check the output generated by
-\f[V]javadoc\f[R].
-.RE
-.IP \[bu] 2
-\f[V]reference\f[R] --- Checks for issues relating to the references to
-Java API elements from documentation comment tags.
-For example, the reference in \f[V]\[at]see\f[R] or
-\f[V]{\[at]link ...}\f[R] cannot be found, or a bad name is given for
-\f[V]\[at]param\f[R] or \f[V]\[at]throws\f[R].
-.RS 2
-.PP
-Issues are typically reported as errors because while the issue may not
-cause problems in the generated files, the author has likely made a
-mistake that will lead to incorrect or unexpected documentation.
-.RE
-.IP \[bu] 2
-\f[V]syntax\f[R] --- Checks for low-level syntactic issues in
-documentation comments.
-For example, unescaped angle brackets (\f[V]<\f[R] and \f[V]>\f[R]) and
-ampersands (\f[V]&\f[R]) and invalid documentation comment tags.
-.RS 2
-.PP
-Issues are typically reported as errors because the issues may lead to
-incorrect or unexpected documentation.
-.RE
-.SS Suppressing Messages
-.PP
-DocLint checks for and recognizes two strings that may be present in the
-arguments for an \f[V]\[at]SuppressWarnings\f[R] annotation.
-.IP \[bu] 2
-\f[V]doclint\f[R]
-.IP \[bu] 2
-\f[V]doclint:\f[R]\f[I]LIST\f[R]
-.PP
-where \f[I]LIST\f[R] is a comma-separated list of one or more of
-\f[V]accessibility\f[R], \f[V]html\f[R], \f[V]missing\f[R],
-\f[V]reference\f[R], \f[V]syntax\f[R].
-.PP
-The names in \f[I]LIST\f[R] are the same \f[B]group\f[R] names supported
-by the command-line \f[V]-Xdoclint\f[R] option for \f[V]javac\f[R] and
-\f[V]javadoc\f[R].
-(This is the same convention honored by the \f[V]javac\f[R]
-\f[V]-Xlint\f[R] option and the corresponding names supported by
-\f[V]\[at]SuppressWarnings\f[R].)
-.PP
-The names in \f[I]LIST\f[R] can equivalently be specified in separate
-arguments of the annotation.
-For example, the following are equivalent:
-.IP \[bu] 2
-\f[V]\[at]SuppressWarnings(\[dq]doclint:accessibility,missing\[dq])\f[R]
-.IP \[bu] 2
-\f[V]\[at]SuppressWarnings(\[dq]doclint:accessibility\[dq], \[dq]doclint:missing\[dq])\f[R]
-.PP
-When DocLint detects an issue in a documentation comment, it checks for
-the presence of \f[V]\[at]SuppressWarnings\f[R] on the associated
-declaration and on all lexically enclosing declarations.
-The issue will be ignored if any such annotation is found containing the
-simple string \f[V]doclint\f[R] or the longer form
-\f[V]doclint:LIST\f[R] where \f[I]LIST\f[R] contains the name of the
-group for the issue.
-.PP
-\f[I]Note:\f[R] as with other uses of \f[V]\[at]SuppressWarnings\f[R],
-using the annotation on a module or package declaration only affects
-that declaration; it does not affect the contents of the module or
-package in other source files.
-.PP
-All messages related to an issue are suppressed by the presence of an
-appropriate \f[V]\[at]SuppressWarnings\f[R] annotation: this includes
-errors as well as warnings.
-.PP
-\f[I]Note:\f[R] It is only possible to \f[I]suppress\f[R] messages.
-If an annotation of \f[V]\[at]SuppressWarnings(\[dq]doclint\[dq])\f[R]
-is given on a top-level declaration, all DocLint messages for that
-declaration and any enclosed declarations will be suppressed; it is not
-possible to selectively re-enable messages for issues in enclosed
-declarations.
-.SS Comparison with downstream validation tools
-.PP
-DocLint is a utility built into \f[V]javac\f[R] and \f[V]javadoc\f[R]
-that checks the content of documentation comments, as found in source
-files.
-In contrast, downstream validation tools can be used to validate the
-output generated from those documentation comments by \f[V]javadoc\f[R]
-and the standard doclet.
-.PP
-Although there is some overlap in functionality, the two mechanisms are
-different and each has its own strengths and weaknesses.
-.IP \[bu] 2
-Downstream validation tools can check the end result of any generated
-documentation, as it will be seen by the end user.
-This includes content from all sources, including documentation
-comments, the standard doclet itself, user-provided taglets, and content
-supplied via command-line options.
-Because such tools are analyzing complete HTML pages, they can do more
-complete checks than can DocLint.
-However, when a problem is found in the generated pages, it can be
-harder to track down exactly where in the build pipeline the problem
-needs to be fixed.
-.IP \[bu] 2
-DocLint checks the content of documentation comments, in source files.
-This makes it very easy to identify the exact position of any issues
-that may be found.
-DocLint can also detect some semantic errors in documentation comments
-that downstream tools cannot detect, such as missing comments, using an
-\f[V]\[at]return\f[R] tag in a method returning \f[V]void\f[R], or an
-\f[V]\[at]param\f[R] tag describing a non-existent parameter.
-But by its nature, DocLint cannot report on problems such as missing
-links, or errors in user-provided custom taglets, or problems in the
-standard doclet itself.
-It also cannot reliably detect errors in documentation comments at the
-boundaries between content in a documentation comment and content
-generated by a custom taglet.
diff --git a/src/jdk.javadoc/share/man/javadoc.md b/src/jdk.javadoc/share/man/javadoc.md
new file mode 100644
index 00000000000..6a1a92e7d16
--- /dev/null
+++ b/src/jdk.javadoc/share/man/javadoc.md
@@ -0,0 +1,1214 @@
+---
+# Copyright (c) 1994, 2024, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JAVADOC(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+javadoc - generate HTML pages of API documentation from Java source files
+
+## Synopsis
+
+`javadoc` \[*options*\] \[*packagenames*\] \[*sourcefiles*\] \[`@`*files*\]
+
+*options*
+:   Specifies command-line options, separated by spaces. See [Standard `javadoc`
+    Options], [Extra `javadoc` Options], [Standard Options for the Standard Doclet],
+    and [Extra Options for the Standard Doclet].
+
+*packagenames*
+:   Specifies names of packages that you want to document, separated by spaces,
+    for example `java.lang java.lang.reflect java.awt`. If you want to also
+    document the subpackages, then use the `-subpackages` option to specify the
+    packages.
+
+    By default, `javadoc` looks for the specified packages in the current
+    directory and subdirectories. Use the `-sourcepath` option to specify the
+    list of directories where to look for packages.
+
+*sourcefiles*
+:   Specifies names of Java source files that you want to document, separated
+    by spaces, for example `Class.java Object.java Button.java`. By default,
+    `javadoc` looks for the specified classes in the current directory.
+    However, you can specify the full path to the class file and use wildcard
+    characters, for example `/home/src/java/awt/Graphics*.java`. You can also
+    specify the path relative to the current directory.
+
+`@`*files*
+:   Specifies names of files that contain a list of `javadoc` tool options,
+    package names, and source file names in any order.
+
+## Description
+
+The `javadoc` tool parses the declarations and documentation comments in a set
+of Java source files and processes them using a pluggable back-end called a
+[_doclet_][doclet].
+
+The [_standard doclet_][standard-doclet] is the one that is used by default,
+and can produce corresponding HTML pages that describe the public and protected
+classes, nested and implicitly declared classes (but not anonymous inner classes),
+interfaces, constructors, methods, and fields. The standard doclet interprets
+the content of documentation comments according to the
+[JavaDoc Documentation Comment Specification for the Standard Doclet][doc-comment-spec].
+Custom tags in documentation comments are supported by means of [taglets][taglet].
+
+You can use the `javadoc` tool and the standard doclet to generate the API
+documentation or the implementation documentation for a set of source files.
+
+You can run the `javadoc` tool on entire packages, individual source files, or
+both. When documenting entire packages, you can use the `-subpackages` option
+either to recursively traverse a directory and its subdirectories, or to pass
+in an explicit list of package names. When you document individual source
+files, pass in a list of Java source file names.
+
+### Documentation Comments
+
+The `javadoc` tool uses the documentation comment, if any, that immediately
+precedes the beginning of the declaration, whether that is an annotation,
+modifier, or the name being declared. If there are multiple documentation
+comments before the declaration, only the last one (closest to the declaration)
+will be used.  If there are any documentation comments after the beginning of
+the declaration, they will be ignored.  To check for any extra or misplaced
+documentation comments, compile your source code with the `javac` option
+`-Xlint`, or more specifically, `-Xlint:dangling-doc-comments`. Within a
+source file, you may suppress any warnings generated by these options
+by using `@SuppressWarnings("dangling-doc-comments")` on a suitable enclosing
+declaration.
+
+[doc-comment-spec]: ../javadoc/doc-comment-spec.html
+[doclet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/Doclet.html
+[standard-doclet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/StandardDoclet.html
+[taglet]: ../../api/jdk.javadoc/jdk/javadoc/doclet/Taglet.html
+
+### Conformance
+
+The standard doclet does not validate the content of documentation comments for
+conformance, nor does it attempt to correct any errors in documentation
+comments. Anyone running javadoc is advised to be aware of the problems that
+may arise when generating non-conformant output or output containing executable
+content, such as JavaScript. The standard doclet does provide the [DocLint](#doclint)
+feature to help developers detect common problems in documentation comments;
+but it is also recommended to check the generated output with any appropriate
+conformance and other checking tools.
+
+For more details on the conformance requirements for HTML5 documents, see
+[Conformance requirements for authors](
+https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors)
+in the HTML5 Specification. For more details on security issues related to web
+pages, see the [Open Web Application Security Project (OWASP)](
+https://www.owasp.org) page.
+
+## Options
+
+`javadoc` supports command-line options for both the main `javadoc` tool
+and the currently selected doclet. The standard doclet is used if no other
+doclet is specified.
+
+GNU-style options (that is, those beginning with `--`) can use an equal sign
+(`=`) instead of whitespace characters to separate the name of an option from
+its value.
+
+### Standard `javadoc` Options
+
+The following core `javadoc` options are equivalent to corresponding `javac`
+options. See *Standard Options* in [javac](javac.html) for the detailed
+descriptions of using these options:
+
+* <span id="option-add-modules">`--add-modules`</span>
+* <span id="option-bootclasspath">`-bootclasspath`</span>
+* <span id="option-class-path">`--class-path`, `-classpath`, or `-cp`</span>
+* <span id="option-disable-line-doc-comments">`--disable-line-doc-comments`</span>
+* <span id="option-enable-preview">`--enable-preview`</span>
+* <span id="option-encoding">`-encoding`</span>
+* <span id="option-extdirs">`-extdirs`</span>
+* <span id="option-limit-modules">`--limit-modules`</span>
+* <span id="option-module">`--module`</span>
+* <span id="option-module-path">`--module-path` or `-p`</span>
+* <span id="option-module-source-path">`--module-source-path`</span>
+* <span id="option-release">`--release`</span>
+* <span id="option-source">`--source` or `-source`</span>
+* <span id="option-source-path">`--source-path` or `-sourcepath`</span>
+* <span id="option-system">`--system`</span>
+* <span id="option-upgrade-module-path">`--upgrade-module-path`</span>
+
+The following options are the core `javadoc` options that are not equivalent to
+a corresponding `javac` option:
+
+<span id="option-breakiterator">`-breakiterator`</span>
+:   Computes the first sentence of the description in a documentation comment
+    using an instance of `java.text.BreakIterator` to detect _sentence breaks_.
+    The rules that are used depend on the [current locale](#option-locale):
+    for example, for English, a sentence break occurs after a period, question mark,
+    or exclamation point followed by a space when the next word starts with a
+    capital letter. (This is meant to handle most abbreviations, such as
+    "The serial no. is valid", but will not handle "Mr. Smith".)
+
+    The option is enabled by default if the language of the current locale is
+    not English. If the language of the current locale is English, and the
+    `-breakiterator` option is not given, a simple default algorithm is used,
+    which just looks for a period followed by a space.
+
+    In a traditional `/**...*/` comment, the search for the end of the first
+    sentence is terminated by an HTML block tag, such as `<p>`, `<pre>`, or
+    the tag for a heading.
+
+    In a Markdown `///` comment, the search for the end of the first sentence
+    skips over any characters enclosed in code spans and links, and is
+    terminated by the end of the initial block, as indicated by a
+    blank line or the beginning of the next block, such as a list, thematic break,
+    or an HTML block.
+
+    The first sentence of the description in a documentation comment is used in
+    summary tables, index pages, and other situations where a short summary is
+    required. For more explicit control in any individual documentation comment,
+    enclose the contents of the first sentence in a `{@summary ...}` tag, or
+    when applicable, in a `{@return ...}` tag.
+
+<span id="option-doclet">`-doclet` *class*</span>
+:   Generates output by using an alternate doclet. Use the fully qualified
+    name. This doclet defines the content and formats the output. If the
+    `-doclet` option isn't used, then the `javadoc` tool uses the standard
+    doclet for generating the default HTML format. This class must implement
+    the `jdk.javadoc.doclet.Doclet` interface. The path to this class is
+    defined by the `-docletpath` option.
+
+<span id="option-docletpath">`-docletpath` *path*</span>
+:   Specifies where to find doclet class files (specified with the `-doclet`
+    option) and any JAR files it depends on. If the starting class file is in a
+    JAR file, then this option specifies the path to that JAR file. You can
+    specify an absolute path or a path relative to the current directory. If
+    `path` contains multiple paths or JAR files, then they should be
+    separated with a colon (`:`) on Linux and macOS, and a semicolon (`;`) on
+    Windows. This option isn't necessary when the `doclet` starting class is
+    already in the search path.
+
+<span id="option-exclude">`-exclude` *pkglist*</span>
+:   Unconditionally, excludes the specified packages and their subpackages from
+    the list formed by `-subpackages`. It excludes those packages even when
+    they would otherwise be included by some earlier or later `-subpackages`
+    option.
+
+    The following example would include `java.io`, `java.util`, and `java.math`
+    (among others), but would exclude packages rooted at `java.net` and
+    `java.lang`. Notice that these examples exclude `java.lang.ref`, which is a
+    subpackage of `java.lang`. Arguments are separated by colons on all
+    operating systems.
+
+    -   **Linux and macOS:**
+
+        ```
+        javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang
+        ```
+
+    -   **Windows:**
+
+        ```
+        javadoc -sourcepath \user\src -subpackages java -exclude java.net:java.lang
+        ```
+
+<span id="option-expand-requires">`--expand-requires` (`transitive`|`all`)</span>
+:   Instructs the javadoc tool to expand the set of modules to be documented.
+    By default, only the modules given explicitly on the command line are
+    documented. Supports the following values:
+
+    -   `transitive`: additionally includes all the required transitive
+        dependencies of those modules.
+
+    -   `all`: includes all dependencies.
+
+<span id="option-help">`--help`, `-help`, `-h`, or `-?`</span>
+:   Prints a synopsis of the standard options.
+
+<span id="option-help-extra">`--help-extra` or `-X`</span>
+:   Prints a synopsis of the set of extra options.
+
+<span id="option-J">`-J`*flag*</span>
+:   Passes *flag* directly to the Java Runtime Environment (JRE) that runs the
+    `javadoc` tool. For example, if you must ensure that the system sets aside
+    32 MB of memory in which to process the generated documentation, then you
+    would call the `-Xmx` option as follows:
+    `javadoc -J-Xmx32m -J-Xms32m com.mypackage`. Be aware that `-Xms` is
+    optional because it only sets the size of initial memory, which is useful
+    when you know the minimum amount of memory required.
+
+    There is no space between the `J` and the `flag`.
+
+    Use the `-version` option to report the version of the JRE being used to
+    run the `javadoc` tool.
+
+    ```
+    javadoc -J-version
+    java version "17" 2021-09-14 LTS
+    Java(TM) SE Runtime Environment (build 17+35-LTS-2724)
+    Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)
+    ```
+
+<span id="option-locale">`-locale` *name*</span>
+:   Specifies the locale that the `javadoc` tool uses when it generates
+    documentation. The argument is the name of the locale, as described in
+    `java.util.Locale` documentation, such as `en_US` (English, United States)
+    or `en_US_WIN` (Windows variant).
+
+    Specifying a locale causes the `javadoc` tool to choose the resource files
+    of that locale for messages such as strings in the navigation bar, headings
+    for lists and tables, help file contents, comments in the `stylesheet.css`
+    file, and so on. It also specifies the sorting order for lists sorted
+    alphabetically, and the sentence separator to determine the end of the
+    first sentence. The `-locale` option doesn't determine the locale of the
+    documentation comment text specified in the source files of the documented
+    classes.
+
+<span id="option-package">`-package`</span>
+:   Shows only package, protected, and public classes and members.
+
+<span id="option-private">`-private`</span>
+:   Shows all classes and members.
+
+<span id="option-protected">`-protected`</span>
+:   Shows only protected and public classes and members. This is the default.
+
+<span id="option-public">`-public`</span>
+:   Shows only the public classes and members.
+
+<span id="option-quiet">`-quiet`</span>
+:   Shuts off messages so that only the warnings and errors appear to make them
+    easier to view. It also suppresses the `version` string.
+
+<span id="option-show-members">`--show-members` *value*</span>
+:   Specifies which members (fields, methods, or constructors) are documented,
+    where *value* can be any of the following:
+
+    * `public` --- shows only public members
+    * `protected` --- shows public and protected members; this is the default
+    * `package` --- shows public, protected, and package members
+    * `private` --- shows all members
+
+<span id="option-show-module-contents">`--show-module-contents` *value*</span>
+:   Specifies the documentation granularity of module declarations, where
+    *value* can be `api` or `all`.
+
+<span id="option-show-packages">`--show-packages` *value*</span>
+:   Specifies which module packages are documented, where *value* can be
+    `exported` or `all` packages.
+
+<span id="option-show-types">`--show-types` *value*</span>
+:   Specifies which types (classes, interfaces, etc.) are documented, where
+    *value* can be any of the following:
+
+    * `public` --- shows only public types
+    * `protected` --- shows public and protected types; this is the default
+    * `package` --- shows public, protected, and package types
+    * `private` --- shows all types
+
+<span id="option-subpackages">`-subpackages` *subpkglist*</span>
+:   Generates documentation from source files in the specified packages and
+    recursively in their subpackages. This option is useful when adding new
+    subpackages to the source code because they are automatically included.
+    Each package argument is any top-level subpackage (such as `java`) or fully
+    qualified package (such as `javax.swing`) that doesn't need to contain
+    source files. Arguments are separated by colons on all operating systems.
+    Wild cards aren't allowed. Use `-sourcepath` to specify where to find the
+    packages. This option doesn't process source files that are in the source
+    tree but don't belong to the packages.
+
+    For example, the following commands generates documentation for packages
+    named `java` and `javax.swing` and all of their subpackages.
+
+    -   **Linux and macOS:**
+
+        ```
+        javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
+        ```
+
+    -   **Windows:**
+
+        ```
+        javadoc -d docs -sourcepath \user\src -subpackages java:javax.swing
+        ```
+
+<span id="option-verbose">`-verbose`</span>
+:   Provides more detailed messages while the `javadoc` tool runs. Without the
+    `-verbose` option, messages appear for loading the source files, generating
+    the documentation (one message per source file), and sorting. The
+    `-verbose` option causes the printing of additional messages that specify
+    the number of milliseconds to parse each Java source file.
+
+<span id="option--version">`--version`</span>
+:   Prints version information.
+
+<span id="option-Werror">`-Werror`</span>
+:   Reports an error if any warnings occur.
+
+Note that if a Java source file contains an implicitly declared class, then
+that class and its public, protected, and package members will be documented
+regardless of the options such as `--show-types`, `--show-members`, `-private`,
+`-protected`, `-package`, and `-public`. If  `--show-members` is specified with
+value `private` or if `-private` is used then all private members of an
+implicitly declared class will be documented too.
+
+### Extra `javadoc` Options
+
+_Note:_ The additional options for `javadoc` are subject to change without
+notice.
+
+The following additional `javadoc` options are equivalent to corresponding
+`javac` options. See *Extra Options* in [javac](javac.html) for the detailed
+descriptions of using these options:
+
+* <span id="option-add-exports">`--add-exports`</span>
+* <span id="option-add-reads">`--add-reads`</span>
+* <span id="option-patch-module">`--patch-module`</span>
+* <span id="option-Xmaxerrs">`-Xmaxerrs`</span>
+* <span id="option-Xmaxwarns">`-Xmaxwarns`</span>
+
+### Standard Options for the Standard Doclet
+
+The following options are provided by the standard doclet.
+
+<span id="option-add-script">`--add-script` *file*</span>
+:   Adds *file* as an additional JavaScript file to the generated documentation.
+    This option can be used one or more times to specify additional script
+    files.
+
+    Command-line example:
+
+    >   `javadoc --add-script first_script.js --add-script
+        second_script.js pkg_foo`
+
+<span id="option-add-stylesheet">`--add-stylesheet` *file*</span>
+:   Adds *file* as an additional stylesheet file to the generated documentation.
+    This option can be used one or more times to specify additional stylesheets
+    included in the documentation.
+
+    Command-line example:
+
+    ```
+    javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo
+    ```
+
+<span id="option-allow-script-in-comments">`--allow-script-in-comments`</span>
+:   Allow JavaScript in documentation comments, and options whose value is
+    _html-code_.
+
+<span id="option-author">`-author`</span>
+:   Includes the text of any `author` tags in the generated documentation.
+
+<span id="option-bottom">`-bottom` *html-code*</span>
+:   Specifies the text to be placed at the bottom of each generated page.
+    The text can contain HTML tags and white space, but when it does, the text
+    must be enclosed in quotation marks. Use escape characters for any internal
+    quotation marks within text.
+
+<span id="option-charset">`-charset` *name*</span>
+:   Specifies the HTML character set for this document. The name should be a
+    preferred MIME name as specified in the [IANA Registry, Character Sets](
+    http://www.iana.org/assignments/character-sets).
+
+    For example:
+
+    ```
+    javadoc -charset "iso-8859-1" mypackage
+    ```
+
+    This command inserts the following line, containing a
+    [`meta` element](https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element)
+    in the head of every generated page:
+
+    ```
+    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+    ```
+
+<span id="option-d">`-d` *directory*</span>
+:   Specifies the destination directory where the `javadoc` tool saves the
+    generated HTML files. If you omit the `-d` option, then the files are saved
+    to the current directory. The `directory` value can be absolute or relative
+    to the current working directory. The destination directory is
+    automatically created when the `javadoc` tool runs.
+
+    -   **Linux and macOS:** For example, the following command
+        generates the documentation for the package `com.mypackage` and saves
+        the results in the `/user/doc/` directory:
+
+        ```
+        javadoc -d /user/doc/ com.mypackage
+        ```
+
+    -   **Windows:** For example, the following command generates the
+        documentation for the package `com.mypackage` and saves the results in
+        the `\user\doc\` directory:
+
+        ```
+        javadoc -d \user\doc\ com.mypackage
+        ```
+
+<span id="option-docencoding">`-docencoding` *name*</span>
+:   Specifies the encoding of the generated HTML files. The name should be a
+    preferred MIME name as specified in the [IANA Registry, Character Sets](
+    http://www.iana.org/assignments/character-sets).
+
+    Three options are available for use in a `javadoc` encoding command. The
+    `-encoding` option is used for encoding the files read by the `javadoc`
+    tool, while the `-docencoding` and `-charset` options are used for encoding
+    the files written by the tool. Of the three available options, at most,
+    only the input and an output encoding option are used in a single encoding
+    command. If you specify both input and output encoding options in a
+    command, they must be the same value. If you specify neither output option,
+    it defaults to the input encoding.
+
+    For example:
+
+    ```
+    javadoc -docencoding "iso-8859-1" mypackage
+    ```
+
+<span id="option-docfilessubdirs">`-docfilessubdirs`</span>
+:   Enables deep copying of `doc-files` directories. Subdirectories and all
+    contents are recursively copied to the destination. For example, the
+    directory `doc-files/example/images` and all of its contents are copied.
+    Use the [`-excludedocfilessubdir`](#option-excludedocfilessubdir) option to
+    restrict the subdirectories to be copied.
+
+<span id="option-doctitle">`-doctitle` *html-code*</span>
+:   Specifies the title to place near the top of the overview summary file. The
+    text specified in the `title` tag is placed as a centered, level-one
+    heading directly beneath the navigation bar. The `title` tag can
+    contain HTML tags and white space, but when it does, you must enclose the
+    title in quotation marks. Additional quotation marks within the `title` tag
+    must be escaped. For example,
+    `javadoc -doctitle "<b>My Library</b><br>v1.0" com.mypackage`.
+
+<span id="option-excludedocfilessubdir">`-excludedocfilessubdir` *name1*`,`*name2...*</span>
+:   Excludes any subdirectories with the given names
+    when recursively copying `doc-files` subdirectories.
+    See [`-docfilessubdirs`](#option-docfilessubdirs).
+    For historical reasons, `:` can be used anywhere in the argument as a
+    separator instead of `,`.
+
+<span id="option-footer">`-footer` *html-code*</span>
+:   This option is no longer supported and reports a warning.
+
+<span id="option-group">`-group` *name* *p1*`,`*p2...*</span>
+:   Group the specified packages together in the Overview page.
+    For historical reasons, `:` can be used as a separator anywhere in the
+    argument instead of `,`.
+
+<span id="option-header">`-header` *html-code*</span>
+:   Specifies the header text to be placed at the top of each output file. The
+    header is placed to the right of the navigation bar. The `header` can
+    contain HTML tags and white space, but when it does, the `header` must be
+    enclosed in quotation marks. Use escape characters for internal quotation
+    marks within a header. For example,
+    `javadoc -header "<b>My Library</b><br>v1.0" com.mypackage`.
+
+<span id="option-helpfile">`-helpfile` *filename*</span>
+:   Specifies a file containing the text that will be displayed when the
+    **HELP** link in the navigation bar is clicked. If this option is not given,
+    the `javadoc` tool creates a default page that will be used.
+
+<span id="option-html5">`-html5`</span>
+:   This option is a no-op and is just retained for backwards compatibility.
+
+<span id="option-javafx">`--javafx` or `-javafx`</span>
+:   Enables JavaFX functionality. This option is enabled by default if the
+    JavaFX library classes are detected on the module path.
+
+<span id="option-keywords">`-keywords`</span>
+:   Adds HTML keyword `<meta>` tags to the generated file for each class. These
+    tags can help search engines that look for `<meta>` tags find the pages.
+    Most search engines that search the entire Internet don't look at `<meta>`
+    tags, because pages can misuse them. Search engines offered by companies
+    that confine their searches to their own website can benefit by looking at
+    `<meta>` tags. The `<meta>` tags include the fully qualified name of the
+    class and the unqualified names of the fields and methods. Constructors
+    aren't included because they are identical to the class name. For example,
+    the page for the class `String` includes these keywords:
+
+    ```
+    <meta name="keywords" content="java.lang.String class">
+    <meta name="keywords" content="CASE_INSENSITIVE_ORDER">
+    <meta name="keywords" content="length()">
+    <meta name="keywords" content="isEmpty()">
+    ```
+
+<span id="option-link">`-link` *url*</span>
+:   Creates links to existing `javadoc` generated documentation of externally
+    referenced classes. The *url* argument is the absolute or relative URL of
+    the directory that contains the external `javadoc` generated documentation.
+    You can specify multiple `-link` options in a specified `javadoc` tool run
+    to link to multiple documents.
+
+    Either a `package-list` or an `element-list` file must be in this *url*
+    directory (otherwise, use the `-linkoffline` option).
+
+    _Note:_ The `package-list` and `element-list` files are generated by the
+    `javadoc` tool when generating the API documentation and should not be
+    modified by the user.
+
+    When you use the `javadoc` tool to document packages, it uses the
+    `package-list` file to determine the packages declared in an API. When you
+    generate API documents for modules, the `javadoc` tool uses the
+    `element-list` file to determine the modules and packages declared in an
+    API.
+
+    The `javadoc` tool reads the names from the appropriate list file and then
+    links to the packages or modules at that URL.
+
+    When the `javadoc` tool runs, the *url* value is copied into the `<a href>`
+    links that are created. Therefore, *url* must be the URL to the directory
+    and not to a file.
+
+    You can use an absolute link for *url* to enable your documents to link to
+    a document on any web site, or you can use a relative link to link only to
+    a relative location. If you use a relative link, then the value you pass in
+    should be the relative path from the destination directory (specified with
+    the `-d` option) to the directory containing the packages being linked to.
+    When you specify an absolute link, you usually use an HTTP link. However,
+    if you want to link to a file system that has no web server, then you can
+    use a file link. Use a file link only when everyone who wants to access the
+    generated documentation shares the same file system. In all cases, and on
+    all operating systems, use a slash as the separator, whether the URL is
+    absolute or relative, and `https:`, `http:`, or `file:` as specified in the
+    [RFC 1738: Uniform Resource Locators (URL)](https://www.rfc-editor.org/info/rfc1738).
+
+    ```
+    -link https://<host>/<directory>/<directory>/.../<name>
+    -link http://<host>/<directory>/<directory>/.../<name>
+    -link file://<host>/<directory>/<directory>/.../<name>
+    -link <directory>/<directory>/.../<name>
+    ```
+
+<span id="option-link-modularity-mismatch">`--link-modularity-mismatch` (`warn`|`info`)</span>
+:   Specifies whether external documentation with wrong modularity (e.g.
+    non-modular documentation for a modular library, or the reverse case)
+    should be reported as a warning (`warn`) or just a message (`info`).
+    The default behavior is to report a warning.
+
+<span id="option-linkoffline">`-linkoffline` *url1* *url2*</span>
+:   This option is a variation of the `-link` option. They both create links to
+    `javadoc` generated documentation for externally referenced classes. You
+    can specify multiple `-linkoffline` options in a specified `javadoc` tool
+    run.
+
+    Use the `-linkoffline` option when:
+
+    -   Linking to a document on the web that the `javadoc` tool can't access
+        through a web connection
+
+    -   The `package-list` or `element-list` file of the external document
+        either isn't accessible or doesn't exist at the URL location, but does
+        exist at a different location and can be specified by either the
+        `package-list` or `element-list` file (typically local).
+
+    _Note:_ The `package-list` and `element-list` files are generated by the
+    `javadoc` tool when generating the API documentation and should not be
+    modified by the user.
+
+    If *url1* is accessible only on the World Wide Web, then the `-linkoffline`
+    option removes the constraint that the `javadoc` tool must have a web
+    connection to generate documentation.
+
+    Another use of the `-linkoffline` option is as a work-around to update
+    documents. After you have run the `javadoc` tool on a full set of packages
+    or modules, you can run the `javadoc` tool again on a smaller set of
+    changed packages or modules, so that the updated files can be inserted back
+    into the original set.
+
+    For example, the `-linkoffline` option takes two arguments. The first is
+    for the string to be embedded in the `<a href>` links, and the second tells
+    the `javadoc` tool where to find either the `package-list` or
+    `element-list` file.
+
+    The *url1* or *url2* value is the absolute or relative URL of the directory
+    that contains the external `javadoc` generated documentation that you want
+    to link to. When relative, the value should be the relative path from the
+    destination directory (specified with the `-d` option) to the root of the
+    packages being linked to. See *url* in the `-link` option.
+
+<span id="option-link-platform-properties">`--link-platform-properties` *url*</span>
+:   Specifies a properties file used to configure links to platform
+    documentation.
+
+    The *url* argument is expected to point to a properties file containing
+    one or more entries with the following format, where `<version>` is the
+    platform version as passed to the `--release` or `--source` option and
+    `<url>` is the base URL of the corresponding platform API documentation:
+
+    ```
+    doclet.platform.docs.<version>=<url>
+    ```
+
+    For instance, a properties file containing URLs for releases 15 to 17 might
+    contain the following lines:
+
+    ```
+    doclet.platform.docs.15=https://example.com/api/15/
+    doclet.platform.docs.16=https://example.com/api/16/
+    doclet.platform.docs.17=https://example.com/api/17/
+    ```
+
+    If the properties file does not contain an entry for a particular release
+    no platform links are generated.
+
+<span id="option-linksource">`-linksource`</span>
+:   Creates an HTML version of each source file (with line numbers) and adds
+    links to them from the standard HTML documentation. Links are created for
+    classes, interfaces, constructors, methods, and fields whose declarations
+    are in a source file. Otherwise, links aren't created, such as for default
+    constructors and generated classes.
+
+    This option exposes all private implementation details in the included
+    source files, including private classes, private fields, and the bodies of
+    private methods, regardless of the `-public`, `-package`, `-protected`, and
+    `-private` options. Unless you also use the `-private` option, not all
+    private classes or interfaces are accessible through links.
+
+    Each link appears on the name of the identifier in its declaration. For
+    example, the link to the source code of the `Button` class would be on the
+    word `Button`:
+
+    ```
+    public class Button extends Component implements Accessible
+    ```
+
+    The link to the source code of the `getLabel` method in the `Button` class
+    is on the word `getLabel`:
+
+    ```
+    public String getLabel()
+    ```
+
+<span id="option-main-stylesheet">`--main-stylesheet` *file* or `-stylesheetfile` *file*</span>
+:   Specifies the path of an alternate stylesheet file that contains the
+    definitions for the CSS styles used in the generated documentation. This
+    option lets you override the default. If you do not specify the option, the
+    `javadoc` tool will create and use a default stylesheet. The file name can
+    be any name and isn't restricted to `stylesheet.css`. The
+    `--main-stylesheet` option is the preferred form.
+
+    Command-line example:
+
+    ```
+    javadoc --main-stylesheet main_stylesheet.css pkg_foo
+    ```
+
+<span id="option-nocomment">`-nocomment`</span>
+:   Suppresses the entire comment body, including the main description and all
+    tags, and generate only declarations. This option lets you reuse source
+    files that were originally intended for a different purpose so that you can
+    produce skeleton HTML documentation during the early stages of a new
+    project.
+
+<span id="option-nodeprecated">`-nodeprecated`</span>
+:   Prevents the generation of any deprecated API in the documentation. This
+    does what the `-nodeprecatedlist` option does, and it doesn't generate any
+    deprecated API throughout the rest of the documentation. This is useful
+    when writing code when you don't want to be distracted by the deprecated
+    code.
+
+<span id="option-nodeprecatedlist">`-nodeprecatedlist`</span>
+:   Prevents the generation of the file that contains the list of deprecated
+    APIs (`deprecated-list.html`) and the link in the navigation bar to that
+    page. The `javadoc` tool continues to generate the deprecated API
+    throughout the rest of the document. This is useful when your source code
+    contains no deprecated APIs, and you want to make the navigation bar
+    cleaner.
+
+<span id="option-no-fonts">`--no-fonts`</span>
+:    Prevents inclusion of font files in the generated documentation. This can
+     be useful if the documentation uses a custom stylesheet which does not
+     use the default fonts.
+
+<span id="option-nohelp">`-nohelp`</span>
+:   Omits the **HELP** link in the navigation bar at the top of each
+    generated page.
+
+<span id="option-noindex">`-noindex`</span>
+:   Omits the index from the generated documents. The index is produced by
+    default.
+
+<span id="option-nonavbar">`-nonavbar`</span>
+:   Prevents the generation of the navigation bar and header. The `-nonavbar`
+    option has no effect on the `-bottom` option. The `-nonavbar` option is
+    useful when you are interested only in the content and have no need for
+    navigation, such as when you are converting the files to PostScript or PDF
+    for printing only.
+
+<span id="option-no-platform-links">`--no-platform-links`</span>
+:   Prevents the generation of links to platform documentation.
+    These links are generated by default.
+
+<span id="option-noqualifier">`-noqualifier` *name1*`,`*name2...*</span>
+:   Excludes the list of qualifiers from the output. The package name is
+    removed from places where class or interface names appear.
+    For historical reasons, `:` can be used anywhere in the argument as a
+    separator instead of `,`.
+
+    The following example omits all package qualifiers: `-noqualifier all`.
+
+    The following example omits `java.lang` and `java.io` package qualifiers:
+    `-noqualifier java.lang:java.io`.
+
+    The following example omits package qualifiers starting with `java` and
+    `com.sun` subpackages, but not `javax: -noqualifier java.*:com.sun.*`.
+
+    Where a package qualifier would appear due to the previous behavior, the
+    name can be suitably shortened. This rule is in effect whether or not the
+    `-noqualifier` option is used.
+
+<span id="option-nosince">`-nosince`</span>
+:   Omits from the generated documentation the `Since` sections derived from
+    any `since` tags.
+
+<span id="option-notimestamp">`-notimestamp`</span>
+:   Suppresses the time stamp, which is hidden in an HTML comment in the
+    generated HTML near the top of each page. The `-notimestamp` option is
+    useful when you want to run the `javadoc` tool on two source bases and
+    compare them, because it prevents time stamps from causing a difference
+    (which would otherwise be a difference on every page). The time stamp
+    includes the `javadoc` tool release number.
+
+<span id="option-notree">`-notree`</span>
+:   Omits the class and interface hierarchy pages from the generated documents.
+    These are the pages you reach using the **TREE** link in the navigation bar.
+    The hierarchy is produced by default.
+
+<span id="option-override-methods">`--override-methods` (`detail`|`summary`)</span>
+:   Documents overridden methods in the detail or summary sections.
+    The default is `detail`.
+
+<span id="option-overview">`-overview` *filename*</span>
+:   Specifies that the `javadoc` tool should retrieve the content for the overview
+    documentation from the file specified by *filename* and place it on
+    the Overview page (`overview-summary.html`). If the *filename* is a relative
+    path, it is evaluated relative to the current working directory.
+
+    The file may be an HTML file, with a filename ending in `.html`,
+    or a Markdown file, with a filename ending in `.md`.
+    If the file is an HTML file, the content for the overview documentation
+    is taken from the `<main>` element in the file, if one is present, or from
+    the `<body>` element is there is no `<main>` element.  If the file is
+    a Markdown file, the entire content of the file is used.
+
+    The title on the overview page is set by `-doctitle`.
+
+    _Note:_ older versions of the `javadoc` tool assumed that any use of this
+    option was for an HTML file, and allowed any extension for the *filename*.
+
+<span id="option-serialwarn">`-serialwarn`</span>
+:   Reports compile-time warnings for missing `@serial` tags. By default,
+    Javadoc reports no serial warnings. Use this option to display the serial
+    warnings, which helps to properly document default serializable fields and
+    `writeExternal` methods.
+
+<span id="option-since">`--since` *release*(`,`*release*)*</span>
+:   Generates documentation for APIs that were added or newly deprecated in the
+    specified *release*s.
+
+    If the `@since` tag in the `javadoc` comment of an element in the documented
+    source code matches a *release* passed as the option argument, information
+    about the element and the release it was added in is included in a "New API"
+    page.
+
+    If the "Deprecated API" page is generated and the `since` element of the
+    `java.lang.Deprecated` annotation of a documented element matches a *release*
+    in the option arguments, information about the release the element was
+    deprecated in is added to the "Deprecated API" page.
+
+    Releases are compared using case-sensitive string comparison.
+
+<span id="option-since-label">`--since-label` *text*</span>
+:   Specifies the *text* to use in the heading of the "New API" page. This may
+    contain information about the releases covered in the page, e.g.
+    "New API in release 2.0", or "New API since release 1".
+
+<span id="option-snippet-path">`--snippet-path` *snippetpathlist*</span>
+:   Specifies the search paths for finding files for external snippets.
+    The *snippetpathlist* can contain multiple paths by separating them with the
+    platform path separator (`;` on Windows; `:` on other platforms.)
+    The standard doclet first searches the `snippet-files` subdirectory in the
+    package containing the snippet, and then searches all the directories in the
+    given list.
+
+<span id="option-sourcetab">`-sourcetab` *tab-length*</span>
+:   Specifies the number of spaces each tab uses in the source.
+
+<span id="option-spec-base-url">`--spec-base-url` *url*</span>
+:   Specifies the base URL for relative URLs in `@spec` tags, to be used when
+    generating links to any external specifications. It can either be an
+    absolute URL, or a relative URL, in which case it is evaluated relative
+    to the base directory of the generated output files. The default value is
+    equivalent to `{@docRoot}/../specs`.
+
+<span id="option-splitindex">`-splitindex`</span>
+:   Splits the index file into multiple files, alphabetically, one file per
+    letter, plus a file for any index entries that start with non-alphabetical
+    symbols.
+
+<span id="option-tag">`-tag` *name*:*locations*:*header*</span>
+:   Specifies a custom tag with a single argument. For the `javadoc` tool to
+    spell-check tag names, it is important to include a `-tag` option for every
+    custom tag that is present in the source code, disabling (with `X`) those
+    that aren't being output in the current run. The colon (`:`) is always the
+    separator. To include a colon in the tag name, escape it with a backward
+    slash (`\`). The `-tag` option outputs the tag heading, *header*, in bold,
+    followed on the next line by the text from its single argument. Similar to
+    any block tag, the argument text can contain inline tags, which are also
+    interpreted. The output is similar to standard one-argument tags, such as
+    the `@return` and `@author` tags. Omitting a *header* value causes the
+    *name* to be the heading.  *locations* is a list of characters specifying
+    the kinds of declarations in which the tag may be used. The following
+    characters may be used, in either uppercase or lowercase:
+
+    * `A`: all declarations
+    * `C`: constructors
+    * `F`: fields
+    * `M`: methods
+    * `O`: the overview page and other documentation files in `doc-files` subdirectories
+    * `P`: packages
+    * `S`: modules
+    * `T`: types (classes and interfaces)
+    * `X`: nowhere: the tag is disabled, and will be ignored
+
+    The order in which tags are given on the command line will be used
+    as the order in which the tags appear in the generated output.
+    You can include standard tags in the order given on the command line
+    by using the `-tag` option with no *locations* or *header*.
+
+<span id="option-taglet">`-taglet` *class*</span>
+:   Specifies the fully qualified name of the taglet used in generating the
+    documentation for that tag. Use the fully qualified name for the *class*
+    value. This taglet also defines the number of text arguments that the
+    custom tag has. The taglet accepts those arguments, processes them, and
+    generates the output.
+
+    Taglets are useful for block or inline tags. They can have any number of
+    arguments and implement custom behavior, such as making text bold,
+    formatting bullets, writing out the text to a file, or starting other
+    processes. Taglets can only determine where a tag should appear and in what
+    form. All other decisions are made by the doclet. A taglet can't do things
+    such as remove a class name from the list of included classes. However, it
+    can execute side effects, such as printing the tag's text to a file or
+    triggering another process. Use the `-tagletpath` option to specify the
+    path to the taglet. The following example inserts the To Do taglet after
+    Parameters and ahead of Throws in the generated pages.
+
+    ```
+    -taglet com.sun.tools.doclets.ToDoTaglet
+    -tagletpath /home/taglets
+    -tag return
+    -tag param
+    -tag todo
+    -tag throws
+    -tag see
+    ```
+
+    Alternately, you can use the `-taglet` option in place of its `-tag`
+    option, but that might be difficult to read.
+
+<span id="option-tagletpath">`-tagletpath` *tagletpathlist*</span>
+:   Specifies the search paths for finding taglet class files.
+    The *tagletpathlist* can contain multiple paths by separating them with the
+    platform path separator (`;` on Windows; `:` on other platforms.)
+    The `javadoc` tool searches all subdirectories of the specified paths.
+
+<span id="option-top">`-top` *html-code*</span>
+:   Specifies the text to be placed at the top of each output file.
+
+<span id="option-use">`-use`</span>
+:   Creates class and package usage pages. Includes one Use page for each
+    documented class and package. The page describes what packages, classes,
+    methods, constructors, and fields use any API of the specified class or
+    package. Given class C, things that use class C would include subclasses of
+    C, fields declared as C, methods that return C, and methods and
+    constructors with parameters of type C. For example, you can look at the
+    Use page for the `String` type. Because the `getName` method in the
+    `java.awt.Font` class returns type `String`, the `getName` method uses
+    `String` and so the `getName` method appears on the Use page for `String`.
+    This documents only uses of the API, not the implementation. When a method
+    uses `String` in its implementation, but doesn't take a string as an
+    argument or return a string, that isn't considered a use of `String`. To
+    access the generated Use page, go to the class or package and click the
+    **USE** link in the navigation bar.
+
+<span id="option-version">`-version`</span>
+:   Includes the text of any `version` tags in the generated documentation.
+    This text is omitted by default.
+    Note: To find out what version of the `javadoc` tool you are using, use
+    the `--version` option (with two hyphens).
+
+<span id="option-windowtitle">`-windowtitle` *title*</span>
+:   Specifies the title to be placed in the HTML `<title>` tag. The text
+    specified in the `title` tag appears in the window title and in any browser
+    bookmarks (favorite places) that someone creates for this page. This title
+    should not contain any HTML tags because a browser will not interpret them
+    correctly. Use escape characters on any internal quotation marks within the
+    `title` tag. If the `-windowtitle` option is omitted, then the `javadoc`
+    tool uses the value of the `-doctitle` option for the `-windowtitle`
+    option. For example, `javadoc -windowtitle "My Library" com.mypackage`.
+
+### Extra Options for the Standard Doclet
+
+The following are additional options provided by the standard doclet and are
+subject to change without notice. Additional options are less commonly
+used or are otherwise regarded as advanced.
+
+<span id="option-date">`--date` *date-and-time*</span>
+:   Specifies the value to be used to timestamp the generated pages, in
+    [ISO 8601][] format. The specified value must be within 10 years of the
+    current date and time. It is an error to specify both `-notimestamp`
+    and `--date`. Using a specific value means the generated documentation
+    can be part of a [reproducible build][]. If the option is not given, the
+    default value is the current date and  time. For example:
+
+    ```
+    javadoc --date 2022-02-01T17:41:59-08:00 mypackage
+    ```
+
+<span id="option-legal-notices">`--legal-notices` (`default`|`none`|*directory*)</span>
+:   Specifies the location from which to copy legal files to the generated
+    documentation. If the option is not specified or is used with the value
+    `default`, the files are copied from the default location.
+    If the argument is used with value `none`, no files are copied. Every
+    other argument is interpreted as directory from which to copy the legal
+    files.
+
+<span id="option-no-frames">`--no-frames`</span>
+:   This option is no longer supported and reports a warning.
+
+<span id="option-Xdoclint">`-Xdoclint`</span>
+:   Enables recommended checks for problems in documentation comments.
+
+    By default, the `-Xdoclint` option is enabled. Disable it with the option
+    `-Xdoclint:none`.
+
+    For more details, see [DocLint](#doclint).
+
+<span id="option-Xdoclint-flags">`-Xdoclint:`*flag*,*flag*,...</span>
+:   Enables or disables specific checks for different kinds of issues in
+    documentation comments.
+
+    Each *flag* can be one of `all`, `none`, or `[-]`*group* where
+    *group* has one of the following values:
+    `accessibility`, `html`, `missing`, `reference`, `syntax`.
+    For more details on these values, see [DocLint Groups](#groups).
+
+    When specifying two or more flags, you can either use a single `-Xdoclint:...`
+    option, listing all the desired flags, or you can use multiple options
+    giving one or more flag in each option. For example, use either of the
+    following commands to check for the HTML, syntax, and accessibility issues
+    in the file `MyFile.java`.
+
+    ```
+    javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility MyFile.java
+    javadoc -Xdoclint:html,syntax,accessibility MyFile.java
+    ```
+
+    The following examples illustrate how to change what DocLint reports:
+
+    * `-Xdoclint:none` --- disables all checks
+    * `-Xdoclint:`*group* --- enables *group* checks
+    * `-Xdoclint:all` --- enables all groups of checks
+    * `-Xdoclint:all,-`*group* --- enables all checks except *group* checks
+
+    For more details, see [DocLint](#doclint).
+
+<span id="option-Xdoclint-package">`-Xdoclint/package:`\[`-`\]*packages*</span>
+:   Enables or disables checks in specific packages. *packages* is a comma
+    separated list of package specifiers. A package specifier is either a
+    qualified name of a package or a package name prefix followed by `*`, which
+    expands to all subpackages of the given package. Prefix the package
+    specifier with `-` to disable checks for the specified packages.
+
+    For more details, see [DocLint](#doclint).
+
+<span id="option-Xdocrootparent">`-Xdocrootparent` *url*</span>
+:   Replaces all `@docRoot` items followed by `/..` in documentation comments
+    with *url*.
+
+[ISO 8601]: https://www.iso.org/iso-8601-date-and-time-format.html
+[reproducible build]: https://reproducible-builds.org/
+
+## DocLint
+
+DocLint provides the ability to check for possible problems in documentation
+comments. Problems may be reported as warnings or errors, depending on their
+severity. For example, a missing comment may be bad style that deserves a
+warning, but a link to an unknown Java declaration is more serious and deserves
+an error. Problems are organized into [groups](#groups), and options can be
+used to enable or disable messages in one or more groups. Within the source
+code, messages in one or more groups can be [suppressed](#suppressing-messages)
+by using `@SuppressWarnings` annotations.
+
+When invoked from `javadoc`, by default DocLint checks all comments that are
+used in the generated documentation. It thus relies on other command-line
+options to determine which declarations, and which corresponding documentation
+comments will be included. _Note:_ this may mean that even comments on some
+private members of serializable classes will also be checked, if the members
+need to be documented in the generated `Serialized Forms` page.
+
+In contrast, when DocLint is invoked from `javac`, DocLint solely relies on the
+various `-Xdoclint...` options to determine which documentation comments to
+check.
+
+DocLint doesn't attempt to fix invalid input, it just reports it.
+
+_Note:_ DocLint doesn't guarantee the completeness of these checks.
+In particular, it isn't a full HTML compliance checker. The goal is to just
+report common errors in a convenient manner.
+
+### Groups
+
+The checks performed by DocLint are organized into groups. The warnings and
+errors in each group can be enabled or disabled with command-line options, or
+suppressed with `@SuppressWarnings` annotations.
+
+The groups are as follows:
+
+* `accessibility` --- Checks for issues related to accessibility.<br>
+  For example, no `alt` attribute specified in an `<img>` element,
+  or no caption or summary attributes specified in a `<table>` element.
+
+  Issues are reported as errors if a downstream validation tool might
+  be expected to report an error in the files generated by `javadoc`.
+
+  For reference, see the [Web Content Accessibility Guidelines][].
+
+
+* `html` --- Detects common high-level HTML issues.<br>
+  For example, putting block elements inside inline elements, or not closing
+  elements that require an end tag.
+
+  Issues are reported as errors if a downstream validation tool might
+  be expected to report an error in the files generated by `javadoc`.
+
+  For reference, see the [HTML Living Standard][].
+
+
+* `missing` --- Checks for missing documentation comments or tags.<br>
+  For example, a missing comment on a class declaration, or a missing `@param`
+  or `@return` tag in the comment for a method declaration.
+
+  Issues related to missing items are typically reported as warnings because
+  they are unlikely to be reported as errors by downstream validation tools
+  that may be used to check the output generated by `javadoc`.
+
+
+* `reference` --- Checks for issues relating to the references to Java API
+  elements from documentation comment tags.<br>
+  For example, the reference in `@see` or `{@link ...}` cannot be found,
+  or a bad name is given for `@param` or `@throws`.
+
+  Issues are typically reported as errors because while the issue may not cause
+  problems in the generated files, the author has likely made a mistake that
+  will lead to incorrect or unexpected documentation.
+
+
+* `syntax` --- Checks for low-level syntactic issues in documentation comments.<br>
+  For example, unescaped angle brackets (`<` and `>`) and ampersands (`&`)
+  and invalid documentation comment tags.<br>
+
+  Issues are typically reported as errors because the issues may
+  lead to incorrect or unexpected documentation.
+
+[HTML Living Standard]: https://html.spec.whatwg.org/multipage/
+[Web Content Accessibility Guidelines]: https://www.w3.org/WAI/standards-guidelines/wcag/
+
+
+### Suppressing Messages
+
+DocLint checks for and recognizes two strings that may be present in the
+arguments for an `@SuppressWarnings` annotation.
+
+* `doclint`
+* `doclint:`_LIST_
+
+where _LIST_ is a comma-separated list of one or more of
+`accessibility`, `html`, `missing`, `reference`, `syntax`.
+
+The names in _LIST_ are the same [group](#groups) names supported by the
+command-line `-Xdoclint` option for `javac` and `javadoc`. (This is the same
+convention honored by the `javac` `-Xlint` option and the corresponding names
+supported by `@SuppressWarnings`.)
+
+The names in _LIST_ can equivalently be specified in separate arguments of
+the annotation. For example, the following are equivalent:
+
+* `@SuppressWarnings("doclint:accessibility,missing")`
+* `@SuppressWarnings("doclint:accessibility", "doclint:missing")`
+
+When DocLint detects an issue in a documentation comment, it checks for the
+presence of `@SuppressWarnings` on the associated declaration and on all
+lexically enclosing declarations. The issue will be ignored if any such
+annotation is found containing the simple string `doclint` or the longer form
+`doclint:LIST` where _LIST_ contains the name of the group for the issue.
+
+_Note:_ as with other uses of `@SuppressWarnings`, using the annotation on a
+module or package declaration only affects that declaration; it does not affect
+the contents of the module or package in other source files.
+
+All messages related to an issue are suppressed by the presence of an
+appropriate `@SuppressWarnings` annotation: this includes errors as well as
+warnings.
+
+_Note:_ It is only possible to *suppress* messages.
+If an annotation of `@SuppressWarnings("doclint")` is given on a top-level
+declaration, all DocLint messages for that declaration and any enclosed
+declarations will be suppressed; it is not possible to selectively re-enable
+messages for issues in enclosed declarations.
+
+
+### Comparison with downstream validation tools
+
+DocLint is a utility built into `javac` and `javadoc` that checks the content
+of documentation comments, as found in source files. In contrast, downstream
+validation tools can be used to validate the output generated from those
+documentation comments by `javadoc` and the standard doclet.
+
+Although there is some overlap in functionality, the two mechanisms are
+different and each has its own strengths and weaknesses.
+
+* Downstream validation tools can check the end result of any generated
+  documentation, as it will be seen by the end user.
+  This includes content from all sources, including documentation comments,
+  the standard doclet itself, user-provided taglets, and content supplied
+  via command-line options. Because such tools are analyzing complete HTML
+  pages, they can do more complete checks than can DocLint.
+  However, when a problem is found in the generated pages, it can be harder to
+  track down exactly where in the build pipeline the problem needs to be fixed.
+
+
+* DocLint checks the content of documentation comments, in source files.
+  This makes it very easy to identify the exact position of any issues that
+  may be found. DocLint can also detect some semantic errors in
+  documentation comments that downstream tools cannot detect,
+  such as missing comments, using an `@return` tag in a method returning `void`,
+  or an `@param` tag describing a non-existent parameter.
+  But by its nature, DocLint cannot report on problems such as
+  missing links, or errors in user-provided custom taglets, or
+  problems in the standard doclet itself. It also cannot reliably
+  detect errors in documentation comments at the boundaries
+  between content in a documentation comment and content generated
+  by a custom taglet.
diff --git a/src/jdk.jcmd/share/man/jcmd.1 b/src/jdk.jcmd/share/man/jcmd.1
deleted file mode 100644
index 495b629089d..00000000000
--- a/src/jdk.jcmd/share/man/jcmd.1
+++ /dev/null
@@ -1,1345 +0,0 @@
-.\" Copyright (c) 2012, 2024, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JCMD" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jcmd - send diagnostic command requests to a running Java Virtual
-Machine (JVM)
-.SH SYNOPSIS
-.PP
-\f[V]jcmd\f[R] [\f[I]pid\f[R] | \f[I]main-class\f[R]]
-\f[I]command\f[R]...
-| \f[V]PerfCounter.print\f[R] | \f[V]-f\f[R] \f[I]filename\f[R]
-.PP
-\f[V]jcmd\f[R] [\f[V]-l\f[R]]
-.PP
-\f[V]jcmd\f[R] \f[V]-h\f[R]
-.TP
-\f[I]pid\f[R]
-When used, the \f[V]jcmd\f[R] utility sends the diagnostic command
-request to the process ID for the Java process.
-.TP
-\f[I]main-class\f[R]
-When used, the \f[V]jcmd\f[R] utility sends the diagnostic command
-request to all Java processes with the specified name of the main class.
-.TP
-\f[I]command\f[R]
-The \f[V]command\f[R] must be a valid \f[V]jcmd\f[R] command for the
-selected JVM.
-The list of available commands for \f[V]jcmd\f[R] is obtained by running
-the \f[V]help\f[R] command (\f[V]jcmd\f[R] \f[I]pid\f[R] \f[V]help\f[R])
-where \f[I]pid\f[R] is the process ID for the running Java process.
-.TP
-\f[V]Perfcounter.print\f[R]
-Prints the performance counters exposed by the specified Java process.
-.TP
-\f[V]-f\f[R] \f[I]filename\f[R]
-Reads and executes commands from a specified file, \f[I]filename\f[R].
-.TP
-\f[V]-l\f[R]
-Displays the list of Java Virtual Machine process identifiers that are
-not running in a separate docker process along with the main class and
-command-line arguments that were used to launch the process.
-If the JVM is in a docker process, you must use tools such as
-\f[V]ps\f[R] to look up the PID.
-.RS
-.PP
-\f[B]Note:\f[R]
-.PP
-Using \f[V]jcmd\f[R] without arguments is the same as using
-\f[V]jcmd -l\f[R].
-.RE
-.TP
-\f[V]-h\f[R]
-Displays the \f[V]jcmd\f[R] utility\[aq]s command-line help.
-.SH DESCRIPTION
-.PP
-The \f[V]jcmd\f[R] utility is used to send diagnostic command requests
-to the JVM.
-It must be used on the same machine on which the JVM is running, and
-have the same effective user and group identifiers that were used to
-launch the JVM.
-Each diagnostic command has its own set of options and arguments.
-To display the description, syntax, and a list of available options and
-arguments for a diagnostic command, use the name of the command as the
-argument.
-For example:
-.RS
-.PP
-\f[V]jcmd\f[R] \f[I]pid\f[R] \f[V]help\f[R] \f[I]command\f[R]
-.RE
-.PP
-If arguments contain spaces, then you must surround them with single or
-double quotation marks (\f[V]\[aq]\f[R] or \f[V]\[dq]\f[R]).
-In addition, you must escape single or double quotation marks with a
-backslash (\f[V]\[rs]\f[R]) to prevent the operating system shell from
-processing quotation marks.
-Alternatively, you can surround these arguments with single quotation
-marks and then with double quotation marks (or with double quotation
-marks and then with single quotation marks).
-.PP
-If you specify the process identifier (\f[I]pid\f[R]) or the main class
-(\f[I]main-class\f[R]) as the first argument, then the \f[V]jcmd\f[R]
-utility sends the diagnostic command request to the Java process with
-the specified identifier or to all Java processes with the specified
-name of the main class.
-You can also send the diagnostic command request to all available Java
-processes by specifying \f[V]0\f[R] as the process identifier.
-.SH COMMANDS FOR JCMD
-.PP
-The \f[I]command\f[R] must be a valid \f[V]jcmd\f[R] diagnostic command
-for the selected JVM.
-The list of available commands for \f[V]jcmd\f[R] is obtained by running
-the \f[V]help\f[R] command (\f[V]jcmd\f[R] \f[I]pid\f[R] \f[V]help\f[R])
-where \f[I]pid\f[R] is the process ID for a running Java process.
-If the \f[I]pid\f[R] is \f[V]0\f[R], commands will be sent to all Java
-processes.
-The main class argument will be used to match, either partially or
-fully, the class used to start Java.
-If no options are given, it lists the running Java process identifiers
-that are not in separate docker processes along with the main class and
-command-line arguments that were used to launch the process (the same as
-using \f[V]-l\f[R]).
-.PP
-\f[V]jcmd\f[R] \f[I]commands\f[R] may take options and arguments.
-\f[I]Options\f[R] are specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-\f[I]Arguments\f[R] are given as just a value, never name=value.
-.PP
-The following commands are available:
-.TP
-\f[V]help\f[R] [\f[I]options\f[R]] [\f[I]arguments\f[R]]
-For more information about a specific command.
-.RS
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]command name\f[R]: The name of the command for which we want help
-(STRING, no default value)
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-all\f[R]: (Optional) Show help for all commands (BOOLEAN, false) .
-.RE
-.TP
-\f[V]Compiler.CodeHeap_Analytics\f[R] [\f[I]function\f[R]] [\f[I]granularity\f[R]]
-Print CodeHeap analytics
-.RS
-.PP
-Impact: Low: Depends on code heap size and content.
-Holds CodeCache_lock during analysis step, usually sub-second duration.
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]function\f[R]: (Optional) Function to be performed (aggregate,
-UsedSpace, FreeSpace, MethodCount, MethodSpace, MethodAge, MethodNames,
-discard (STRING, all)
-.IP \[bu] 2
-\f[I]granularity\f[R]: (Optional) Detail level - smaller value -> more
-detail (INT, 4096)
-.RE
-.TP
-\f[V]Compiler.codecache\f[R]
-Prints code cache layout and bounds.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]Compiler.codelist\f[R]
-Prints all compiled methods in code cache that are alive.
-.RS
-.PP
-Impact: Medium
-.RE
-.TP
-\f[V]Compiler.directives_add\f[R] \f[I]arguments\f[R]
-Adds compiler directives from a file.
-.RS
-.PP
-Impact: Low
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]filename\f[R]: The name of the directives file (STRING, no default
-value)
-.RE
-.TP
-\f[V]Compiler.directives_clear\f[R]
-Remove all compiler directives.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]Compiler.directives_print\f[R]
-Prints all active compiler directives.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]Compiler.directives_remove\f[R]
-Remove latest added compiler directive.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]Compiler.memory\f[R] [\f[I]options\f[R]]
-Print compilation footprint
-.RS
-.PP
-Impact: Medium: Pause time depends on number of compiled methods
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-H\f[R]: (Optional) Human readable format (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-s\f[R]: (Optional) Minimum memory size (MEMORY SIZE, 0)
-.RE
-.TP
-\f[V]Compiler.perfmap\f[R] [\f[I]arguments\f[R]] (Linux only)
-Write map file for Linux perf tool.
-.RS
-.PP
-Impact: Low
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]filename\f[R]: (Optional) The name of the map file.
-If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
-(FILE, \[dq]/tmp/perf-%p.map\[dq])
-.RE
-.TP
-\f[V]Compiler.queue\f[R]
-Prints methods queued for compilation.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]GC.class_histogram\f[R] [\f[I]options\f[R]]
-Provides statistics about the Java heap usage.
-.RS
-.PP
-Impact: High --- depends on Java heap size and content.
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-all\f[R]: (Optional) Inspects all objects, including unreachable
-objects (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-parallel\f[R]: (Optional) Number of parallel threads to use for
-heap inspection.
-0 (the default) means let the VM determine the number of threads to use.
-1 means use one thread (disable parallelism).
-For any other value the VM will try to use the specified number of
-threads, but might use fewer.
-(INT, 0)
-.RE
-.TP
-\f[V]GC.finalizer_info\f[R]
-Provides information about the Java finalization queue.
-.RS
-.PP
-Impact: Medium
-.RE
-.TP
-\f[V]GC.heap_dump\f[R] [\f[I]options\f[R]] \f[I]filename\f[R]
-Generates a HPROF format dump of the Java heap.
-.RS
-.PP
-Impact: High --- depends on the Java heap size and content.
-Request a full GC unless the \f[V]-all\f[R] option is specified.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-all\f[R]: (Optional) Dump all objects, including unreachable
-objects (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-gz\f[R]: (Optional) If specified, the heap dump is written in
-gzipped format using the given compression level.
-1 (recommended) is the fastest, 9 the strongest compression.
-(INT, 1)
-.IP \[bu] 2
-\f[V]-overwrite\f[R]: (Optional) If specified, the dump file will be
-overwritten if it exists (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-parallel\f[R]: (Optional) Number of parallel threads to use for
-heap dump.
-The VM will try to use the specified number of threads, but might use
-fewer.
-(INT, 1)
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]filename\f[R]: The name of the dump file.
-If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
-(FILE, no default value)
-.RE
-.TP
-\f[V]GC.heap_info\f[R]
-Provides generic Java heap information.
-.RS
-.PP
-Impact: Medium
-.RE
-.TP
-\f[V]GC.run\f[R]
-Calls \f[V]java.lang.System.gc()\f[R].
-.RS
-.PP
-Impact: Medium --- depends on the Java heap size and content.
-.RE
-.TP
-\f[V]GC.run_finalization\f[R]
-Calls \f[V]java.lang.System.runFinalization()\f[R].
-.RS
-.PP
-Impact: Medium --- depends on the Java content.
-.RE
-.TP
-\f[V]JFR.check\f[R] [\f[I]options\f[R]]
-Show information about a running flight recording
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-If no parameters are entered, information for all active recordings is
-shown.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]name\f[R]: (Optional) Name of the flight recording.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]verbose\f[R]: (Optional) Flag for printing the event settings for
-the recording (BOOLEAN, false)
-.RE
-.TP
-\f[V]JFR.configure\f[R] [\f[I]options\f[R]]
-Set the parameters for a flight recording
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-If no parameters are entered, the current settings are displayed.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]dumppath\f[R]: (Optional) Path to the location where a recording
-file is written in case the VM runs into a critical error, such as a
-system crash.
-(STRING, The default location is the current directory)
-.IP \[bu] 2
-\f[V]globalbuffercount\f[R]: (Optional) Number of global buffers.
-This option is a legacy option: change the \f[V]memorysize\f[R]
-parameter to alter the number of global buffers.
-This value cannot be changed once JFR has been initialized.
-(STRING, default determined by the value for \f[V]memorysize\f[R])
-.IP \[bu] 2
-\f[V]globalbuffersize\f[R]: (Optional) Size of the global buffers, in
-bytes.
-This option is a legacy option: change the \f[V]memorysize\f[R]
-parameter to alter the size of the global buffers.
-This value cannot be changed once JFR has been initialized.
-(STRING, default determined by the value for \f[V]memorysize\f[R])
-.IP \[bu] 2
-\f[V]maxchunksize\f[R]: (Optional) Maximum size of an individual data
-chunk in bytes if one of the following suffixes is not used: \[aq]m\[aq]
-or \[aq]M\[aq] for megabytes OR \[aq]g\[aq] or \[aq]G\[aq] for
-gigabytes.
-This value cannot be changed once JFR has been initialized.
-(STRING, 12M)
-.IP \[bu] 2
-\f[V]memorysize\f[R]: (Optional) Overall memory size, in bytes if one of
-the following suffixes is not used: \[aq]m\[aq] or \[aq]M\[aq] for
-megabytes OR \[aq]g\[aq] or \[aq]G\[aq] for gigabytes.
-This value cannot be changed once JFR has been initialized.
-(STRING, 10M)
-.IP \[bu] 2
-\f[V]repositorypath\f[R]: (Optional) Path to the location where
-recordings are stored until they are written to a permanent file.
-(STRING, The default location is the temporary directory for the
-operating system.
-On Linux operating systems, the temporary directory is \f[V]/tmp\f[R].
-On Windwows, the temporary directory is specified by the \f[V]TMP\f[R]
-environment variable.)
-.IP \[bu] 2
-\f[V]preserve-repository=\f[R]{\f[V]true\f[R]|\f[V]false\f[R]} :
-Specifies whether files stored in the disk repository should be kept
-after the JVM has exited.
-If false, files are deleted.
-By default, this parameter is disabled.
-.IP \[bu] 2
-\f[V]stackdepth\f[R]: (Optional) Stack depth for stack traces.
-Setting this value greater than the default of 64 may cause a
-performance degradation.
-This value cannot be changed once JFR has been initialized.
-(LONG, 64)
-.IP \[bu] 2
-\f[V]thread_buffer_size\f[R]: (Optional) Local buffer size for each
-thread in bytes if one of the following suffixes is not used:
-\[aq]k\[aq] or \[aq]K\[aq] for kilobytes or \[aq]m\[aq] or \[aq]M\[aq]
-for megabytes.
-Overriding this parameter could reduce performance and is not
-recommended.
-This value cannot be changed once JFR has been initialized.
-(STRING, 8k)
-.IP \[bu] 2
-\f[V]samplethreads\f[R]: (Optional) Flag for activating thread sampling.
-(BOOLEAN, true)
-.RE
-.TP
-\f[V]JFR.dump\f[R] [\f[I]options\f[R]]
-Write data to a file while a flight recording is running
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-No options are required.
-The recording continues to run after the data is written.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]begin\f[R]: (Optional) Specify the time from which recording data
-will be included in the dump file.
-The format is specified as local time.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]end\f[R]: (Optional) Specify the time to which recording data will
-be included in the dump file.
-The format is specified as local time.
-(STRING, no default value)
-.RS 2
-.PP
-\f[B]Note:\f[R] For both \f[V]begin\f[R] and \f[V]end\f[R], the time
-must be in a format that can be read by
-java.time.LocalTime::parse(STRING),
-java.time.LocalDateTime::parse(STRING) or
-java.time.Instant::parse(STRING).
-For example, \[dq]13:20:15\[dq], \[dq]2020-03-17T09:00:00\[dq] or
-\[dq]2020-03-17T09:00:00Z\[dq].
-.PP
-\f[B]Note:\f[R] \f[V]begin\f[R] and \f[V]end\f[R] times correspond to
-the timestamps found within the recorded information in the flight
-recording data.
-.PP
-Another option is to use a time relative to the current time that is
-specified by a negative integer followed by \[dq]s\[dq], \[dq]m\[dq] or
-\[dq]h\[dq].
-For example, \[dq]-12h\[dq], \[dq]-15m\[dq] or \[dq]-30s\[dq]
-.RE
-.IP \[bu] 2
-\f[V]filename\f[R]: (Optional) Name of the file to which the flight
-recording data is dumped.
-If no filename is given, a filename is generated from the PID and the
-current date.
-The filename may also be a directory in which case, the filename is
-generated from the PID and the current date in the specified directory.
-If %p and/or %t is specified in the filename, it expands to the
-JVM\[aq]s PID and the current timestamp, respectively.
-(FILE, no default value)
-.IP \[bu] 2
-\f[V]maxage\f[R]: (Optional) Length of time for dumping the flight
-recording data to a file.
-(INTEGER followed by \[aq]s\[aq] for seconds \[aq]m\[aq] for minutes or
-\[aq]h\[aq] for hours, no default value)
-.IP \[bu] 2
-\f[V]maxsize\f[R]: (Optional) Maximum size for the amount of data to
-dump from a flight recording in bytes if one of the following suffixes
-is not used: \[aq]m\[aq] or \[aq]M\[aq] for megabytes OR \[aq]g\[aq] or
-\[aq]G\[aq] for gigabytes.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]name\f[R]: (Optional) Name of the recording.
-If no name is given, data from all recordings is dumped.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]path-to-gc-roots\f[R]: (Optional) Flag for saving the path to
-garbage collection (GC) roots at the time the recording data is dumped.
-The path information is useful for finding memory leaks but collecting
-it can cause the application to pause for a short period of time.
-Turn on this flag only when you have an application that you suspect has
-a memory leak.
-(BOOLEAN, false)
-.RE
-.TP
-\f[V]JFR.start\f[R] [\f[I]options\f[R]]
-Start a flight recording
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-If no parameters are entered, then a recording is started with default
-values.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]delay\f[R]: (Optional) Length of time to wait before starting to
-record (INTEGER followed by \[aq]s\[aq] for seconds \[aq]m\[aq] for
-minutes or \[aq]h\[aq] for hours, 0s)
-.IP \[bu] 2
-\f[V]disk\f[R]: (Optional) Flag for also writing the data to disk while
-recording (BOOLEAN, true)
-.IP \[bu] 2
-\f[V]dumponexit\f[R]: (Optional) Flag for writing the recording to disk
-when the Java Virtual Machine (JVM) shuts down.
-If set to \[aq]true\[aq] and no value is given for \f[V]filename\f[R],
-the recording is written to a file in the directory where the process
-was started.
-The file name is a system-generated name that contains the process ID,
-the recording ID and the current time stamp.
-(For example: \f[V]id-1-2019_12_12_10_41.jfr\f[R]) (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]duration\f[R]: (Optional) Length of time to record.
-Note that \f[V]0s\f[R] means forever (INTEGER followed by \[aq]s\[aq]
-for seconds \[aq]m\[aq] for minutes or \[aq]h\[aq] for hours, 0s)
-.IP \[bu] 2
-\f[V]filename\f[R]: (Optional) Name of the file to which the flight
-recording data is written when the recording is stopped.
-If no filename is given, a filename is generated from the PID and the
-current date and is placed in the directory where the process was
-started.
-The filename may also be a directory in which case, the filename is
-generated from the PID and the current date in the specified directory.
-If %p and/or %t is specified in the filename, it expands to the
-JVM\[aq]s PID and the current timestamp, respectively.
-(FILE, no default value)
-.IP \[bu] 2
-\f[V]maxage\f[R]: (Optional) Maximum time to keep the recorded data on
-disk.
-This parameter is valid only when the \f[V]disk\f[R] parameter is set to
-\f[V]true\f[R].
-Note \f[V]0s\f[R] means forever.
-(INTEGER followed by \[aq]s\[aq] for seconds \[aq]m\[aq] for minutes or
-\[aq]h\[aq] for hours, 0s)
-.IP \[bu] 2
-\f[V]maxsize\f[R]: (Optional) Maximum size of the data to keep on disk
-in bytes if one of the following suffixes is not used: \[aq]m\[aq] or
-\[aq]M\[aq] for megabytes OR \[aq]g\[aq] or \[aq]G\[aq] for gigabytes.
-This parameter is valid only when the \f[V]disk\f[R] parameter is set to
-\[aq]true\[aq].
-The value must not be less than the value for the \f[V]maxchunksize\f[R]
-parameter set with the \f[V]JFR.configure\f[R] command.
-(STRING, 0 (no maximum size))
-.IP \[bu] 2
-\f[V]name\f[R]: (Optional) Name of the recording.
-If no name is provided, a name is generated.
-Make note of the generated name that is shown in the response to the
-command so that you can use it with other commands.
-(STRING, system-generated default name)
-.IP \[bu] 2
-\f[V]path-to-gc-roots\f[R]: (Optional) Flag for saving the path to
-garbage collection (GC) roots at the end of a recording.
-The path information is useful for finding memory leaks but collecting
-it is time consuming.
-Turn on this flag only when you have an application that you suspect has
-a memory leak.
-If the \f[V]settings\f[R] parameter is set to \[aq]profile\[aq], then
-the information collected includes the stack trace from where the
-potential leaking object was allocated.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]settings\f[R]: (Optional) Name of the settings file that identifies
-which events to record.
-To specify more than one file, separate the names with a comma
-(\[aq],\[aq]).
-Include the path if the file is not in \f[V]JAVA-HOME\f[R]/lib/jfr.
-The following profiles are included with the JDK in the
-\f[V]JAVA-HOME\f[R]/lib/jfr directory: \[aq]default.jfc\[aq]: collects a
-predefined set of information with low overhead, so it has minimal
-impact on performance and can be used with recordings that run
-continuously; \[aq]profile.jfc\[aq]: Provides more data than the
-\[aq]default.jfc\[aq] profile, but with more overhead and impact on
-performance.
-Use this configuration for short periods of time when more information
-is needed.
-Use \f[V]none\f[R] to start a recording without a predefined
-configuration file.
-(STRING, \f[V]JAVA-HOME\f[R]/lib/jfr/default.jfc)
-.PP
-Event settings and .jfc options can be specified using the following
-syntax:
-.IP \[bu] 2
-\f[V]option\f[R]: (Optional) Specifies the option value to modify.
-To list available options, use the \f[V]JAVA_HOME\f[R]/bin/jfr tool.
-.IP \[bu] 2
-\f[V]event-setting\f[R]: (Optional) Specifies the event setting value to
-modify.
-Use the form: \f[V]<event-name>#<setting-name>=<value>\f[R] To add a new
-event setting, prefix the event name with \[aq]+\[aq].
-.PP
-You can specify values for multiple event settings and .jfc options by
-separating them with a whitespace.
-In case of a conflict between a parameter and a .jfc option, the
-parameter will take precedence.
-The whitespace delimiter can be omitted for timespan values, i.e.
-20ms.
-For more information about the settings syntax, see Javadoc of the
-jdk.jfr package.
-.RE
-.TP
-\f[V]JFR.stop\f[R] [\f[I]options\f[R]]
-Stop a flight recording
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-If no parameters are entered, then no recording is stopped.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]filename\f[R]: (Optional) Name of the file to which the recording
-is written when the recording is stopped.
-If %p and/or %t is specified in the filename, it expands to the
-JVM\[aq]s PID and the current timestamp, respectively.
-If no path is provided, the data from the recording is discarded.
-(FILE, no default value)
-.IP \[bu] 2
-\f[V]name\f[R]: (Optional) Name of the recording (STRING, no default
-value)
-.RE
-.TP
-\f[V]JFR.view\f[R] [\f[I]options\f[R]]
-Display event data in predefined views.
-.RS
-.PP
-Impact: Medium
-.PP
-\f[B]Note:\f[R]
-.PP
-The \f[I]options\f[R] must be specified using either \f[I]key\f[R] or
-\f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-If no parameters are entered, then a list of available views are
-displayed.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]cell-height\f[R]: (Optional) Maximum number of rows in a table
-cell.
-(INT, default value depends on the view)
-.IP \[bu] 2
-\f[V]maxage\f[R]: (Optional) Length of time for the view to span.
-(INT followed by \[aq]s\[aq] for seconds \[aq]m\[aq] for minutes or
-\[aq]h\[aq] for hours, default value is 10m)
-.IP \[bu] 2
-\f[V]maxsize\f[R]: (Optional) Maximum size for the view to span in bytes
-if one of the following suffixes is not used: \[aq]m\[aq] or \[aq]M\[aq]
-for megabytes OR \[aq]g\[aq] or \[aq]G\[aq] for gigabytes.
-(STRING, default value is 32MB)
-.IP \[bu] 2
-\f[V]truncate\f[R]: (Optional) Maximum number of rows in a table cell.
-(INT, default value depends on the view)
-.IP \[bu] 2
-\f[V]verbose\f[R]: (Optional) Displays the query that makes up the view.
-(BOOLEAN, default value is false)
-.IP \[bu] 2
-\f[V]width\f[R]: (Optional) The width of the view in characters.
-(INT, default value depends on the view)
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[V]view\f[R]: Name of the view or event type to display.
-Use \f[V]help JFR.view\f[R] to see a list of available views.
-(STRING, no default value)
-.PP
-The view parameter can be an event type name.
-Use \f[V]JFR.view types\f[R] to see a list.
-To display all views, use \f[V]JFR.view all-views\f[R].
-To display all events, use \f[V]JFR.view all-events\f[R].
-.RE
-.TP
-\f[V]JVMTI.agent_load\f[R] [\f[I]arguments\f[R]]
-Loads JVMTI native agent.
-.RS
-.PP
-Impact: Low
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]library path\f[R]: Absolute path of the JVMTI agent to load.
-(STRING, no default value)
-.IP \[bu] 2
-\f[I]agent option\f[R]: (Optional) Option string to pass the agent.
-(STRING, no default value)
-.RE
-.TP
-\f[V]JVMTI.data_dump\f[R]
-Signal the JVM to do a data-dump request for JVMTI.
-.RS
-.PP
-Impact: High
-.RE
-.TP
-\f[V]ManagementAgent.start\f[R] [\f[I]options\f[R]]
-Starts remote management agent.
-.RS
-.PP
-Impact: Low --- no impact
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]config.file\f[R]: (Optional) Sets
-\f[V]com.sun.management.config.file\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jmxremote.host\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.host\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jmxremote.port\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.port\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jmxremote.rmi.port\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.rmi.port\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-\f[V]jmxremote.ssl\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.ssl\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jmxremote.registry.ssl\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.registry.ssl\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-\f[V]jmxremote.authenticate\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.authenticate\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-jmxremote.password.file: (Optional) Sets
-\f[V]com.sun.management.jmxremote.password.file\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-\f[V]jmxremote.access.file\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.acce ss.file\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-\f[V]jmxremote.login.config\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.log in.config\f[R] (STRING, no default
-value)
-.IP \[bu] 2
-\f[V]jmxremote.ssl.enabled.cipher.suites\f[R]: (Optional) Sets
-\f[V]com.sun.management\f[R].
-.IP \[bu] 2
-\f[V]jmxremote.ssl.enabled.cipher.suite\f[R]: (STRING, no default value)
-.IP \[bu] 2
-\f[V]jmxremote.ssl.enabled.protocols\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxr emote.ssl.enabled.protocols\f[R] (STRING,
-no default value)
-.IP \[bu] 2
-\f[V]jmxremote.ssl.need.client.auth\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxre mote.need.client.auth\f[R] (STRING, no
-default value)
-.IP \[bu] 2
-\f[V]jmxremote.ssl.config.file\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote. ssl_config_file\f[R] (STRING, no
-default value)
-.IP \[bu] 2
-\f[V]jmxremote.autodiscovery\f[R]: (Optional) Sets
-\f[V]com.sun.management.jmxremote.au todiscovery\f[R] (STRING, no
-default value)
-.IP \[bu] 2
-\f[V]jdp.port\f[R]: (Optional) Sets
-\f[V]com.sun.management.jdp.port\f[R] (INT, no default value)
-.IP \[bu] 2
-\f[V]jdp.address\f[R]: (Optional) Sets
-\f[V]com.sun.management.jdp.address\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jdp.source_addr\f[R]: (Optional) Sets
-\f[V]com.sun.management.jdp.source_addr\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[V]jdp.ttl\f[R]: (Optional) Sets \f[V]com.sun.management.jdp.ttl\f[R]
-(INT, no default value)
-.IP \[bu] 2
-\f[V]jdp.pause\f[R]: (Optional) Sets
-\f[V]com.sun.management.jdp.pause\f[R] (INT, no default value)
-.IP \[bu] 2
-\f[V]jdp.name\f[R]: (Optional) Sets
-\f[V]com.sun.management.jdp.name\f[R] (STRING, no default value)
-.RE
-.TP
-\f[V]ManagementAgent.start_local\f[R]
-Starts the local management agent.
-.RS
-.PP
-Impact: Low --- no impact
-.RE
-.TP
-\f[V]ManagementAgent.status\f[R]
-Print the management agent status.
-.RS
-.PP
-Impact: Low --- no impact
-.RE
-.TP
-\f[V]ManagementAgent.stop\f[R]
-Stops the remote management agent.
-.RS
-.PP
-Impact: Low --- no impact
-.RE
-.TP
-\f[V]System.dump_map\f[R] [\f[I]options\f[R]] (Linux only)
-Dumps an annotated process memory map to an output file.
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-H\f[R]: (Optional) Human readable format (BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-F\f[R]: (Optional) File path.
-If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
-(FILE, \[dq]vm_memory_map_%p.txt\[dq])
-.RE
-.TP
-\f[V]System.map\f[R] [\f[I]options\f[R]] (Linux only)
-Prints an annotated process memory map of the VM process.
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-H\f[R]: (Optional) Human readable format (BOOLEAN, false)
-.RE
-.TP
-\f[V]System.native_heap_info\f[R] (Linux only)
-Attempts to output information regarding native heap usage through
-malloc_info(3).
-If unsuccessful outputs \[dq]Error: \[dq] and a reason.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]System.trim_native_heap\f[R] (Linux only)
-Attempts to free up memory by trimming the C-heap.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]Thread.dump_to_file\f[R] [\f[I]options\f[R]] \f[I]filepath\f[R]
-Dump threads, with stack traces, to a file in plain text or JSON format.
-.RS
-.PP
-Impact: Medium: Depends on the number of threads.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-overwrite\f[R]: (Optional) May overwrite existing file (BOOLEAN,
-false)
-.IP \[bu] 2
-\f[V]-format\f[R]: (Optional) Output format (\[dq]plain\[dq] or
-\[dq]json\[dq]) (STRING, plain)
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]filepath\f[R]: The file path to the output file.
-If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
-(FILE, no default value)
-.RE
-.TP
-\f[V]Thread.print\f[R] [\f[I]options\f[R]]
-Prints all threads with stacktraces.
-.RS
-.PP
-Impact: Medium --- depends on the number of threads.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-e\f[R]: (Optional) Print extended thread information (BOOLEAN,
-false)
-.IP \[bu] 2
-\f[V]-l\f[R]: (Optional) Prints \f[V]java.util.concurrent\f[R] locks
-(BOOLEAN, false)
-.RE
-.TP
-\f[V]VM.cds\f[R] [\f[I]arguments\f[R]]
-Dump a static or dynamic shared archive that includes all currently
-loaded classes.
-.RS
-.PP
-Impact: Medium --- pause time depends on number of loaded classes
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]subcmd\f[R]: must be either \f[V]static_dump\f[R] or
-\f[V]dynamic_dump\f[R] (STRING, no default value)
-.IP \[bu] 2
-\f[I]filename\f[R]: (Optional) Name of the shared archive to be dumped.
-If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
-(FILE, \[dq]java_pid%p_<subcmd>.jsa\[dq])
-.PP
-If \f[V]dynamic_dump\f[R] is specified, the target JVM must be started
-with the JVM option \f[V]-XX:+RecordDynamicDumpInfo\f[R].
-.RE
-.TP
-\f[V]VM.class_hierarchy\f[R] [\f[I]options\f[R]] [\f[I]arguments\f[R]]
-Print a list of all loaded classes, indented to show the class
-hierarchy.
-The name of each class is followed by the ClassLoaderData* of its
-ClassLoader, or \[dq]null\[dq] if it is loaded by the bootstrap class
-loader.
-.RS
-.PP
-Impact: Medium --- depends on the number of loaded classes.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-i\f[R]: (Optional) Inherited interfaces should be printed.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]-s\f[R]: (Optional) If a classname is specified, print its
-subclasses in addition to its superclasses.
-Without this option only the superclasses will be printed.
-(BOOLEAN, false)
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]classname\f[R]: (Optional) The name of the class whose hierarchy
-should be printed.
-If not specified, all class hierarchies are printed.
-(STRING, no default value)
-.RE
-.TP
-\f[V]VM.classes\f[R] [\f[I]options\f[R]]
-Print all loaded classes
-.RS
-.PP
-Impact: Medium: Depends on number of loaded classes.
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-verbose\f[R]: (Optional) Dump the detailed content of a Java
-class.
-Some classes are annotated with flags: \f[V]F\f[R] = has, or inherits, a
-non-empty finalize method, \f[V]f\f[R] = has final method, \f[V]W\f[R] =
-methods rewritten, \f[V]C\f[R] = marked with \f[V]\[at]Contended\f[R]
-annotation, \f[V]R\f[R] = has been redefined, \f[V]S\f[R] = is shared
-class (BOOLEAN, false)
-.RE
-.TP
-\f[V]VM.classloader_stats\f[R]
-Print statistics about all ClassLoaders.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]VM.classloaders\f[R] [\f[I]options\f[R]]
-Prints classloader hierarchy.
-.RS
-.PP
-Impact: Medium --- Depends on number of class loaders and classes
-loaded.
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]show-classes\f[R]: (Optional) Print loaded classes.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]verbose\f[R]: (Optional) Print detailed information.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]fold\f[R]: (Optional) Show loaders of the same name and class as
-one.
-(BOOLEAN, true)
-.RE
-.TP
-\f[V]VM.command_line\f[R]
-Print the command line used to start this VM instance.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]VM.dynlibs\f[R]
-Print loaded dynamic libraries.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]VM.events\f[R] [\f[I]options\f[R]]
-Print VM event logs
-.RS
-.PP
-Impact: Low --- Depends on event log size.
-.PP
-\f[I]options\f[R]:
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.IP \[bu] 2
-\f[V]log\f[R]: (Optional) Name of log to be printed.
-If omitted, all logs are printed.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]max\f[R]: (Optional) Maximum number of events to be printed (newest
-first).
-If omitted, all events are printed.
-(STRING, no default value)
-.RE
-.TP
-\f[V]VM.flags\f[R] [\f[I]options\f[R]]
-Print the VM flag options and their current values.
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-all\f[R]: (Optional) Prints all flags supported by the VM
-(BOOLEAN, false).
-.RE
-.TP
-\f[V]VM.info\f[R]
-Print information about the JVM environment and status.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]VM.log\f[R] [\f[I]options\f[R]]
-Lists current log configuration, enables/disables/configures a log
-output, or rotates all logs.
-.RS
-.PP
-Impact: Low
-.PP
-\f[I]options\f[R]:
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.IP \[bu] 2
-\f[V]output\f[R]: (Optional) The name or index (#) of output to
-configure.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]output_options\f[R]: (Optional) Options for the output.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]what\f[R]: (Optional) Configures what tags to log.
-(STRING, no default value )
-.IP \[bu] 2
-\f[V]decorators\f[R]: (Optional) Configures which decorators to use.
-Use \[aq]none\[aq] or an empty value to remove all.
-(STRING, no default value)
-.IP \[bu] 2
-\f[V]disable\f[R]: (Optional) Turns off all logging and clears the log
-configuration.
-(BOOLEAN, no default value)
-.IP \[bu] 2
-\f[V]list\f[R]: (Optional) Lists current log configuration.
-(BOOLEAN, no default value)
-.IP \[bu] 2
-\f[V]rotate\f[R]: (Optional) Rotates all logs.
-(BOOLEAN, no default value)
-.RE
-.TP
-\f[V]VM.metaspace\f[R] [\f[I]options\f[R]]
-Prints the statistics for the metaspace
-.RS
-.PP
-Impact: Medium --- Depends on number of classes loaded.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]basic\f[R]: (Optional) Prints a basic summary (does not need a
-safepoint).
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]show-loaders\f[R]: (Optional) Shows usage by class loader.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]show-classes\f[R]: (Optional) If show-loaders is set, shows loaded
-classes for each loader.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]by-chunktype\f[R]: (Optional) Break down numbers by chunk type.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]by-spacetype\f[R]: (Optional) Break down numbers by loader type.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]vslist\f[R]: (Optional) Shows details about the underlying virtual
-space.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]chunkfreelist\f[R]: (Optional) Shows details about global chunk
-free lists (ChunkManager).
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]scale\f[R]: (Optional) Memory usage in which to scale.
-Valid values are: 1, KB, MB or GB (fixed scale) or \[dq]dynamic\[dq] for
-a dynamically chosen scale.
-(STRING, dynamic)
-.RE
-.TP
-\f[V]VM.native_memory\f[R] [\f[I]options\f[R]]
-Print native memory usage
-.RS
-.PP
-Impact: Medium
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]summary\f[R]: (Optional) Requests runtime to report current memory
-summary, which includes total reserved and committed memory, along with
-memory usage summary by each subsystem.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]detail\f[R]: (Optional) Requests runtime to report memory
-allocation >= 1K by each callsite.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]baseline\f[R]: (Optional) Requests runtime to baseline current
-memory usage, so it can be compared against in later time.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]summary.diff\f[R]: (Optional) Requests runtime to report memory
-summary comparison against previous baseline.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]detail.diff\f[R]: (Optional) Requests runtime to report memory
-detail comparison against previous baseline, which shows the memory
-allocation activities at different callsites.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]statistics\f[R]: (Optional) Prints tracker statistics for tuning
-purpose.
-(BOOLEAN, false)
-.IP \[bu] 2
-\f[V]scale\f[R]: (Optional) Memory usage in which scale, KB, MB or GB
-(STRING, KB)
-.RE
-.TP
-\f[V]VM.set_flag\f[R] [\f[I]arguments\f[R]]
-Sets VM flag option using the provided value.
-.RS
-.PP
-Impact: Low
-.PP
-\f[I]arguments\f[R]:
-.IP \[bu] 2
-\f[I]flag name\f[R]: The name of the flag that you want to set (STRING,
-no default value)
-.IP \[bu] 2
-\f[I]string value\f[R]: (Optional) The value that you want to set
-(STRING, no default value)
-.RE
-.TP
-\f[V]VM.stringtable\f[R] [\f[I]options\f[R]]
-Dump string table.
-.RS
-.PP
-Impact: Medium --- depends on the Java content.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-verbose\f[R]: (Optional) Dumps the content of each string in the
-table (BOOLEAN, false)
-.RE
-.TP
-\f[V]VM.symboltable\f[R] [\f[I]options\f[R]]
-Dump symbol table.
-.RS
-.PP
-Impact: Medium --- depends on the Java content.
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax).
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-verbose\f[R]: (Optional) Dumps the content of each symbol in the
-table (BOOLEAN, false)
-.RE
-.TP
-\f[V]VM.system_properties\f[R]
-Print system properties.
-.RS
-.PP
-Impact: Low
-.RE
-.TP
-\f[V]VM.systemdictionary\f[R]
-Prints the statistics for dictionary hashtable sizes and bucket length.
-.RS
-.PP
-Impact: Medium
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]verbose\f[R]: (Optional) Dump the content of each dictionary entry
-for all class loaders (BOOLEAN, false) .
-.RE
-.TP
-\f[V]VM.uptime\f[R] [\f[I]options\f[R]]
-Print VM uptime.
-.RS
-.PP
-Impact: Low
-.PP
-\f[B]Note:\f[R]
-.PP
-The following \f[I]options\f[R] must be specified using either
-\f[I]key\f[R] or \f[I]key\f[R]\f[V]=\f[R]\f[I]value\f[R] syntax.
-.PP
-\f[I]options\f[R]:
-.IP \[bu] 2
-\f[V]-date\f[R]: (Optional) Adds a prefix with the current date
-(BOOLEAN, false)
-.RE
-.TP
-\f[V]VM.version\f[R]
-Print JVM version information.
-.RS
-.PP
-Impact: Low
-.RE
diff --git a/src/jdk.jcmd/share/man/jcmd.md b/src/jdk.jcmd/share/man/jcmd.md
new file mode 100644
index 00000000000..448dfdd3051
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jcmd.md
@@ -0,0 +1,1032 @@
+---
+# Copyright (c) 2012, 2024, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JCMD(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jcmd - send diagnostic command requests to a running Java Virtual Machine
+(JVM)
+
+## Synopsis
+
+`jcmd` \[*pid* \| *main-class*\] *command*... \| `PerfCounter.print` \| `-f`
+*filename*
+
+`jcmd` \[`-l`\]
+
+`jcmd` `-h`
+
+*pid*
+:   When used, the `jcmd` utility sends the diagnostic command request to the
+    process ID for the Java process.
+
+*main-class*
+:   When used, the `jcmd` utility sends the diagnostic command request to all
+    Java processes with the specified name of the main class.
+
+*command*
+:   The `command` must be a valid `jcmd` command for the selected JVM. The list
+    of available commands for `jcmd` is obtained by running the `help` command
+    (`jcmd` *pid* `help`) where *pid* is the process ID for the running Java
+    process.
+
+`Perfcounter.print`
+:   Prints the performance counters exposed by the specified Java process.
+
+`-f` *filename*
+:   Reads and executes commands from a specified file, *filename*.
+
+`-l`
+:   Displays the list of Java Virtual Machine process identifiers that are not
+    running in a separate docker process along with the main class and
+    command-line arguments that were used to launch the process. If the JVM is
+    in a docker process, you must use tools such as `ps` to look up the PID.
+
+    **Note:**
+
+    Using `jcmd` without arguments is the same as using `jcmd -l`.
+
+`-h`
+:   Displays the `jcmd` utility's command-line help.
+
+## Description
+
+The `jcmd` utility is used to send diagnostic command requests to the JVM. It
+must be used on the same machine on which the JVM is running, and have the same
+effective user and group identifiers that were used to launch the JVM. Each
+diagnostic command has its own set of options and arguments. To display the description,
+syntax, and a list of available options and arguments for a diagnostic command, use the
+name of the command as the argument. For example:
+
+>   `jcmd` *pid* `help` *command*
+
+If arguments contain spaces, then you must surround them with single or double
+quotation marks (`'` or `"`). In addition, you must escape single or double
+quotation marks with a backslash (`\`) to prevent the operating system shell
+from processing quotation marks. Alternatively, you can surround these
+arguments with single quotation marks and then with double quotation marks (or
+with double quotation marks and then with single quotation marks).
+
+If you specify the process identifier (*pid*) or the main class (*main-class*)
+as the first argument, then the `jcmd` utility sends the diagnostic command
+request to the Java process with the specified identifier or to all Java
+processes with the specified name of the main class. You can also send the
+diagnostic command request to all available Java processes by specifying `0` as
+the process identifier.
+
+## Commands for jcmd
+
+The *command* must be a valid `jcmd` diagnostic command for the selected JVM.
+The list of available commands for `jcmd` is obtained by running the `help`
+command (`jcmd` *pid* `help`) where *pid* is the process ID for a running Java
+process. If the *pid* is `0`, commands will be sent to all Java processes. The
+main class argument will be used to match, either partially or fully, the class
+used to start Java. If no options are given, it lists the running Java process
+identifiers that are not in separate docker processes along with the main class
+and command-line arguments that were used to launch the process (the same as
+using `-l`).
+
+`jcmd` *commands* may take options and arguments.  *Options* are specified using
+either *key* or *key*`=`*value* syntax.  *Arguments* are given as just a value,
+never name=value.
+
+
+The following commands are available:
+
+`help` \[*options*\] \[*arguments*\]
+:   For more information about a specific command.
+
+    *arguments*:
+
+    -   *command name*: The name of the command for which we want help (STRING,
+        no default value)
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-all`: (Optional) Show help for all commands (BOOLEAN, false) .
+
+`Compiler.CodeHeap_Analytics`  \[*function*\] \[*granularity*\]
+:   Print CodeHeap analytics
+
+    Impact: Low: Depends on code heap size and content. Holds CodeCache_lock during analysis step, usually sub-second duration.
+
+    *arguments*:
+
+    -   *function*: (Optional) Function to be performed (aggregate, UsedSpace, FreeSpace, MethodCount, MethodSpace, MethodAge, MethodNames, discard (STRING, all)
+
+    -   *granularity*: (Optional) Detail level - smaller value -> more detail (INT, 4096)
+
+`Compiler.codecache`
+:   Prints code cache layout and bounds.
+
+    Impact: Low
+
+`Compiler.codelist`
+:   Prints all compiled methods in code cache that are alive.
+
+    Impact: Medium
+
+`Compiler.directives_add` *arguments*
+:   Adds compiler directives from a file.
+
+    Impact: Low
+
+    *arguments*:
+
+    -   *filename*: The name of the directives file (STRING, no default value)
+
+`Compiler.directives_clear`
+:   Remove all compiler directives.
+
+    Impact: Low
+
+`Compiler.directives_print`
+:   Prints all active compiler directives.
+
+    Impact: Low
+
+`Compiler.directives_remove`
+:   Remove latest added compiler directive.
+
+    Impact: Low
+
+`Compiler.memory` \[*options*\]
+:   Print compilation footprint
+
+    Impact: Medium: Pause time depends on number of compiled methods
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax.
+
+    *options*:
+
+    -   `-H`: (Optional) Human readable format (BOOLEAN, false)
+    -   `-s`: (Optional) Minimum memory size (MEMORY SIZE, 0)
+
+`Compiler.perfmap` \[*arguments*\] (Linux only)
+:   Write map file for Linux perf tool.
+
+    Impact: Low
+
+    *arguments*:
+
+    -   *filename*: (Optional) The name of the map file.  If %p is specified in the filename, it is expanded to the JVM's PID. (FILE, "/tmp/perf-%p.map")
+
+`Compiler.queue`
+:   Prints methods queued for compilation.
+
+    Impact: Low
+
+`GC.class_histogram` \[*options*\]
+:   Provides statistics about the Java heap usage.
+
+    Impact: High --- depends on Java heap size and content.
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax.
+
+    *options*:
+
+    -   `-all`: (Optional) Inspects all objects, including unreachable objects
+        (BOOLEAN, false)
+    -  `-parallel`: (Optional) Number of parallel threads to use for heap inspection.
+       0 (the default) means let the VM determine the number of threads to use.
+       1 means use one thread (disable parallelism). For any other value the VM will
+       try to use the specified number of threads, but might use fewer. (INT, 0)
+
+`GC.finalizer_info`
+:   Provides information about the Java finalization queue.
+
+    Impact: Medium
+
+`GC.heap_dump` \[*options*\] *filename*
+:   Generates a HPROF format dump of the Java heap.
+
+    Impact: High --- depends on the Java heap size and content. Request a full
+    GC unless the `-all` option is specified.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-all`: (Optional) Dump all objects, including unreachable objects
+        (BOOLEAN, false)
+    -   `-gz`: (Optional) If specified, the heap dump is written in gzipped format
+         using the given compression level. 1 (recommended) is the fastest, 9 the
+         strongest compression. (INT, 1)
+    -   `-overwrite`: (Optional) If specified, the dump file will be overwritten if
+         it exists (BOOLEAN, false)
+    -   `-parallel`: (Optional) Number of parallel threads to use for heap dump. The VM will try to use the specified number of threads, but might use fewer. (INT, 1)
+
+    *arguments*:
+
+    -   *filename*: The name of the dump file.  If %p is specified in the filename, it is expanded to the JVM's PID. (FILE, no default value)
+
+`GC.heap_info`
+:   Provides generic Java heap information.
+
+    Impact: Medium
+
+`GC.run`
+:   Calls `java.lang.System.gc()`.
+
+    Impact: Medium --- depends on the Java heap size and content.
+
+`GC.run_finalization`
+:   Calls `java.lang.System.runFinalization()`.
+
+    Impact: Medium --- depends on the Java content.
+
+`JFR.check` \[*options*\]
+:   Show information about a running flight recording
+
+    Impact: Low
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax. If no parameters are entered, information for all active recordings is shown.
+
+    *options*:
+
+    -   `name`: (Optional) Name of the flight recording. (STRING, no default value)
+
+    -   `verbose`: (Optional) Flag for printing the event settings for the recording
+        (BOOLEAN, false)
+
+`JFR.configure` \[*options*\]
+:   Set the parameters for a flight recording
+
+    Impact: Low
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax. If no parameters are entered, the current settings are displayed.
+
+    *options*:
+
+    -   `dumppath`: (Optional) Path to the location where a recording file is written
+        in case the VM runs into a critical error, such as a system
+        crash. (STRING, The default location is the current directory)
+
+    -   `globalbuffercount`: (Optional) Number of global buffers. This option is
+        a legacy option: change the `memorysize` parameter to alter the number of
+        global buffers. This value cannot be changed once JFR has been initialized.
+        (STRING, default determined by the value for `memorysize`)
+
+    -   `globalbuffersize`: (Optional) Size of the global buffers, in bytes. This
+        option is a legacy option: change the `memorysize` parameter to alter
+        the size of the global buffers. This value cannot be changed once JFR
+        has been initialized. (STRING, default determined by the value for `memorysize`)
+
+    -   `maxchunksize`: (Optional) Maximum size of an individual data chunk in bytes
+        if one of the following suffixes is not used: 'm' or 'M' for megabytes OR
+        'g' or 'G' for gigabytes. This value cannot be changed once JFR has been
+        initialized. (STRING, 12M)
+
+    -   `memorysize`: (Optional) Overall memory size, in bytes if one of the following
+        suffixes is not used: 'm' or 'M' for megabytes OR 'g' or 'G' for gigabytes.
+        This value cannot be changed once JFR has been initialized. (STRING, 10M)
+
+    -   `repositorypath`: (Optional) Path to the location where recordings are stored
+        until they are written to a permanent file. (STRING, The default location is
+        the temporary directory for the operating system. On Linux operating systems,
+        the temporary directory is `/tmp`. On Windwows, the temporary directory is
+        specified by the `TMP` environment variable.)
+
+    -   `preserve-repository=`{`true`\|`false`} : Specifies whether files stored in
+        the disk repository should be kept after the JVM has exited. If false, files
+        are deleted. By default, this parameter is disabled.
+
+    -   `stackdepth`: (Optional) Stack depth for stack traces. Setting this value
+        greater than the default of 64 may cause a performance degradation.
+        This value cannot be changed once JFR has been initialized.  (LONG, 64)
+
+    -   `thread_buffer_size`: (Optional) Local buffer size for each thread in bytes if one
+        of the following suffixes is not used: 'k' or 'K' for kilobytes or 'm' or 'M'
+        for megabytes. Overriding this parameter could reduce performance and is
+        not recommended. This value cannot be changed once JFR has been initialized.
+        (STRING, 8k)
+
+    -   `samplethreads`: (Optional) Flag for activating thread sampling. (BOOLEAN, true)
+
+`JFR.dump` \[*options*\]
+:   Write data to a file while a flight recording is running
+
+    Impact: Low
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value* syntax.
+    No options are required. The recording continues to run after the data is written.
+
+    *options*:
+
+    -   `begin`: (Optional) Specify the time from which recording data will be included
+        in the dump file. The format is specified as local time. (STRING, no default value)
+
+    -   `end`: (Optional) Specify the time to which recording data will be included in the
+        dump file. The format is specified as local time. (STRING, no default value)
+
+        **Note:** For both `begin` and `end`, the time must be in a format that can be read
+        by java.time.LocalTime::parse(STRING), java.time.LocalDateTime::parse(STRING)
+        or java.time.Instant::parse(STRING). For example, "13:20:15", "2020-03-17T09:00:00"
+        or "2020-03-17T09:00:00Z".
+
+        **Note:** `begin` and `end` times correspond to the timestamps found within the recorded
+        information in the flight recording data.
+
+        Another option is to use a time relative to the current time that is specified
+        by a negative integer followed by "s", "m" or "h".  For example, "-12h", "-15m" or "-30s"
+
+    -   `filename`: (Optional) Name of the file to which the flight recording data
+        is dumped. If no filename is given, a filename is generated from the PID and
+        the current date. The filename may also be a directory in which case, the filename
+        is generated from the PID and the current date in the specified directory.
+        If %p and/or %t is specified in the filename, it expands to the JVM's PID and
+        the current timestamp, respectively.
+        (FILE, no default value)
+
+    -   `maxage`: (Optional) Length of time for dumping the flight recording data
+        to a file. (INTEGER followed by 's' for seconds 'm' for minutes or 'h' for hours,
+        no default value)
+
+    -   `maxsize`: (Optional) Maximum size for the amount of data to dump from a flight
+        recording in bytes if one of the following suffixes is not used: 'm' or 'M' for megabytes
+        OR 'g' or 'G' for gigabytes. (STRING, no default value)
+
+    -   `name`: (Optional) Name of the recording. If no name is given, data
+        from all recordings is dumped. (STRING, no default value)
+
+    -   `path-to-gc-roots`: (Optional) Flag for saving the path to garbage collection (GC)
+        roots at the time the recording data is dumped. The path information is useful for
+        finding memory leaks but collecting it can cause the application to pause for
+        a short period of time. Turn on this flag only when you have an application
+        that you suspect has a memory leak. (BOOLEAN, false)
+
+`JFR.start` \[*options*\]
+:   Start a flight recording
+
+    Impact: Low
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax. If no parameters are entered, then a recording is started with default values.
+
+    *options*:
+
+    -   `delay`: (Optional) Length of time to wait before starting to record
+        (INTEGER followed by 's' for seconds 'm' for minutes or 'h' for hours, 0s)
+
+    -   `disk`: (Optional) Flag for also writing the data to disk while recording
+        (BOOLEAN, true)
+
+    -   `dumponexit`: (Optional) Flag for writing the recording to disk when the
+        Java Virtual Machine (JVM) shuts down. If set to 'true' and no value is given
+        for `filename`, the recording is written to a file in the directory where
+        the process was started. The file name is a system-generated name that
+        contains the process ID, the recording ID and the current time stamp.
+        (For example: `id-1-2019_12_12_10_41.jfr`) (BOOLEAN, false)
+
+    -   `duration`: (Optional) Length of time to record. Note that `0s` means forever
+        (INTEGER followed by 's' for seconds 'm' for minutes or 'h' for hours, 0s)
+
+    -   `filename`: (Optional) Name of the file to which the flight recording data
+        is written when the recording is stopped. If no filename is given, a filename
+        is generated from the PID and the current date and is placed in the directory
+        where the process was started. The filename may also be a directory in which case,
+        the filename is generated from the PID and the current date in the specified directory.
+        If %p and/or %t is specified in the filename, it expands to the JVM's PID
+        and the current timestamp, respectively.
+        (FILE, no default value)
+
+    -   `maxage`: (Optional) Maximum time to keep the recorded data on disk. This
+        parameter is valid only when the `disk` parameter is set to `true`. Note
+        `0s` means forever. (INTEGER followed by 's' for seconds 'm'
+        for minutes or 'h' for hours, 0s)
+
+    -   `maxsize`: (Optional) Maximum size of the data to keep on disk in bytes if one
+        of the following suffixes is not used: 'm' or 'M' for megabytes OR 'g' or 'G' for gigabytes.
+        This parameter is valid only when the `disk` parameter is set to 'true'. The value must
+        not be less than the value for the `maxchunksize` parameter set with the `JFR.configure` command.
+        (STRING, 0 (no maximum size))
+
+    -   `name`: (Optional) Name of the recording. If no name is provided, a name is generated.
+        Make note of the generated name that is shown in the response to the command so that
+        you can use it with other commands. (STRING, system-generated default name)
+
+    -   `path-to-gc-roots`: (Optional) Flag for saving the path to garbage collection (GC)
+        roots at the end of a recording. The path information is useful for finding memory leaks
+        but collecting it is time consuming. Turn on this flag only when you
+        have an application that you suspect has a memory leak. If the `settings` parameter
+        is set to 'profile', then the information collected includes the stack trace
+        from where the potential leaking object was allocated. (BOOLEAN, false)
+
+    -   `settings`: (Optional) Name of the settings file that identifies which events to record.
+        To specify more than one file, separate the names with a comma (','). Include the path
+        if the file is not in `JAVA-HOME`/lib/jfr. The following profiles are included with
+        the JDK in the `JAVA-HOME`/lib/jfr directory: 'default.jfc': collects a predefined set
+        of information with low overhead, so it has minimal impact on performance and can be
+        used with recordings that run continuously; 'profile.jfc': Provides more data than the
+        'default.jfc' profile, but with more overhead and impact on performance. Use this
+        configuration for short periods of time when more information is needed. Use `none` to
+        start a recording without a predefined configuration file.
+        (STRING, `JAVA-HOME`/lib/jfr/default.jfc)
+
+    Event settings and .jfc options can be specified using the following syntax:
+
+    -   `option`: (Optional) Specifies the option value to modify. To list available
+        options, use the `JAVA_HOME`/bin/jfr tool.
+
+    -   `event-setting`: (Optional) Specifies the event setting value to modify. Use the form:
+        `<event-name>#<setting-name>=<value>`
+        To add a new event setting, prefix the event name with '+'.
+
+    You can specify values for multiple event settings and .jfc options by
+    separating them with a whitespace. In case of a conflict between a parameter
+    and a .jfc option, the parameter will take precedence. The whitespace
+    delimiter can be omitted for timespan values, i.e. 20ms. For more
+    information about the settings syntax, see Javadoc of the jdk.jfr
+    package.
+
+`JFR.stop` \[*options*\]
+:   Stop a flight recording
+
+    Impact: Low
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax. If no parameters are entered, then no recording is stopped.
+
+    *options*:
+
+    -   `filename`: (Optional) Name of the file to which the recording is
+        written when the recording is stopped. If %p and/or %t is specified
+        in the filename, it expands to the JVM's PID and the current
+        timestamp, respectively. If no path is provided, the data from the
+        recording is discarded. (FILE, no default value)
+
+    -   `name`: (Optional) Name of the recording (STRING, no default value)
+
+
+`JFR.view` \[*options*\]
+:   Display event data in predefined views.
+
+    Impact: Medium
+
+    **Note:**
+
+    The *options* must be specified using either *key* or *key*`=`*value*
+    syntax. If no parameters are entered, then a list of available views
+    are displayed.
+
+    *options*:
+
+    -   `cell-height`: (Optional) Maximum number of rows in a table cell.
+        (INT, default value depends on the view)
+
+    -   `maxage`: (Optional) Length of time for the view to span.
+        (INT followed by 's' for seconds 'm' for minutes or 'h' for hours,
+        default value is 10m)
+
+    -   `maxsize`: (Optional) Maximum size for the view to span in bytes if one
+        of the following suffixes is not used: 'm' or 'M' for megabytes OR
+        'g' or 'G' for gigabytes. (STRING, default value is 32MB)
+
+    -   `truncate`: (Optional) Maximum number of rows in a table cell.
+        (INT, default value depends on the view)
+
+    -   `verbose`: (Optional) Displays the query that makes up the view.
+        (BOOLEAN, default value is false)
+
+    -   `width`: (Optional) The width of the view in characters. (INT,
+        default value depends on the view)
+
+    *arguments*:
+
+    -   `view`: Name of the view or event type to display. Use `help JFR.view`
+        to see a list of available views. (STRING, no default value)
+
+    The view parameter can be an event type name. Use `JFR.view types` to see
+    a list. To display all views, use `JFR.view all-views`. To display all
+    events, use `JFR.view all-events`.
+
+`JVMTI.agent_load` \[*arguments*\]
+:   Loads JVMTI native agent.
+
+    Impact: Low
+
+    *arguments*:
+
+    -   *library path*: Absolute path of the JVMTI agent to load. (STRING, no
+        default value)
+
+    -   *agent option*: (Optional) Option string to pass the agent. (STRING, no
+        default value)
+
+`JVMTI.data_dump`
+:   Signal the JVM to do a data-dump request for JVMTI.
+
+    Impact: High
+
+`ManagementAgent.start` \[*options*\]
+:   Starts remote management agent.
+
+    Impact: Low --- no impact
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `config.file`: (Optional) Sets `com.sun.management.config.file`
+        (STRING, no default value)
+
+    -   `jmxremote.host`: (Optional) Sets `com.sun.management.jmxremote.host`
+        (STRING, no default value)
+
+    -   `jmxremote.port`: (Optional) Sets `com.sun.management.jmxremote.port`
+        (STRING, no default value)
+
+    -   `jmxremote.rmi.port`: (Optional) Sets
+        `com.sun.management.jmxremote.rmi.port` (STRING, no default value)
+
+    -   `jmxremote.ssl`: (Optional) Sets `com.sun.management.jmxremote.ssl`
+        (STRING, no default value)
+
+    -   `jmxremote.registry.ssl`: (Optional) Sets
+        `com.sun.management.jmxremote.registry.ssl` (STRING, no default value)
+
+    -   `jmxremote.authenticate`: (Optional) Sets
+        `com.sun.management.jmxremote.authenticate` (STRING, no default value)
+
+    -   jmxremote.password.file: (Optional) Sets
+        `com.sun.management.jmxremote.password.file` (STRING, no default value)
+
+    -   `jmxremote.access.file`: (Optional) Sets
+        `com.sun.management.jmxremote.acce ss.file` (STRING, no default value)
+
+    -   `jmxremote.login.config`: (Optional) Sets
+        `com.sun.management.jmxremote.log in.config` (STRING, no default value)
+
+    -   `jmxremote.ssl.enabled.cipher.suites`: (Optional) Sets
+        `com.sun.management`.
+
+    -   `jmxremote.ssl.enabled.cipher.suite`: (STRING, no default value)
+
+    -   `jmxremote.ssl.enabled.protocols`: (Optional) Sets
+        `com.sun.management.jmxr emote.ssl.enabled.protocols` (STRING, no
+        default value)
+
+    -   `jmxremote.ssl.need.client.auth`: (Optional) Sets
+        `com.sun.management.jmxre mote.need.client.auth` (STRING, no default
+        value)
+
+    -   `jmxremote.ssl.config.file`: (Optional) Sets
+        `com.sun.management.jmxremote. ssl_config_file` (STRING, no default
+        value)
+
+    -   `jmxremote.autodiscovery`: (Optional) Sets
+        `com.sun.management.jmxremote.au todiscovery` (STRING, no default
+        value)
+
+    -   `jdp.port`: (Optional) Sets `com.sun.management.jdp.port` (INT, no
+        default value)
+
+    -   `jdp.address`: (Optional) Sets `com.sun.management.jdp.address`
+        (STRING, no default value)
+
+    -   `jdp.source_addr`: (Optional) Sets `com.sun.management.jdp.source_addr`
+        (STRING, no default value)
+
+    -   `jdp.ttl`: (Optional) Sets `com.sun.management.jdp.ttl` (INT, no
+        default value)
+
+    -   `jdp.pause`: (Optional) Sets `com.sun.management.jdp.pause` (INT, no
+        default value)
+
+    -   `jdp.name`: (Optional) Sets `com.sun.management.jdp.name` (STRING, no
+        default value)
+
+`ManagementAgent.start_local`
+:   Starts the local management agent.
+
+    Impact: Low --- no impact
+
+`ManagementAgent.status`
+:   Print the management agent status.
+
+    Impact: Low --- no impact
+
+`ManagementAgent.stop`
+:   Stops the remote management agent.
+
+    Impact: Low --- no impact
+
+`System.dump_map` \[*options*\] (Linux only)
+:   Dumps an annotated process memory map to an output file.
+
+    Impact: Low
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -    `-H`: (Optional) Human readable format (BOOLEAN, false)
+    -    `-F`: (Optional) File path.  If %p is specified in the filename, it is expanded to the JVM's PID.  (FILE, "vm_memory_map_%p.txt")
+
+`System.map` \[*options*\] (Linux only)
+:   Prints an annotated process memory map of the VM process.
+
+    Impact: Low
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -    `-H`: (Optional) Human readable format (BOOLEAN, false)
+
+`System.native_heap_info` (Linux only)
+:   Attempts to output information regarding native heap usage through malloc_info(3). If unsuccessful outputs "Error: " and a reason.
+
+    Impact: Low
+
+`System.trim_native_heap` (Linux only)
+:   Attempts to free up memory by trimming the C-heap.
+
+    Impact: Low
+
+`Thread.dump_to_file` \[*options*\] *filepath*
+:   Dump threads, with stack traces, to a file in plain text or JSON format.
+
+    Impact: Medium: Depends on the number of threads.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-overwrite`: (Optional) May overwrite existing file (BOOLEAN, false)
+    -   `-format`: (Optional) Output format ("plain" or "json") (STRING, plain)
+
+    *arguments*:
+
+    -   *filepath*:  The file path to the output file.  If %p is specified in the filename, it is expanded to the JVM's PID.  (FILE, no default value)
+
+`Thread.print` \[*options*\]
+:   Prints all threads with stacktraces.
+
+    Impact: Medium --- depends on the number of threads.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-e`: (Optional) Print extended thread information (BOOLEAN, false)
+    -   `-l`: (Optional) Prints `java.util.concurrent` locks (BOOLEAN, false)
+
+`VM.cds` \[*arguments*\]
+:   Dump a static or dynamic shared archive that includes all currently loaded classes.
+
+    Impact: Medium --- pause time depends on number of loaded classes
+
+    *arguments*:
+
+    -   *subcmd*:  must be either `static_dump` or `dynamic_dump` (STRING, no default value)
+    -   *filename*: (Optional) Name of the shared archive to be dumped.  If %p is specified in the filename, it is expanded to the JVM's PID.  (FILE, "java_pid%p_\<subcmd\>.jsa")
+
+    If `dynamic_dump` is specified, the target JVM must be started with the JVM option
+    `-XX:+RecordDynamicDumpInfo`.
+
+`VM.class_hierarchy` \[*options*\] \[*arguments*\]
+:   Print a list of all loaded classes, indented to show the class hierarchy.
+    The name of each class is followed by the ClassLoaderData\* of its
+    ClassLoader, or "null" if it is loaded by the bootstrap class loader.
+
+    Impact: Medium --- depends on the number of loaded classes.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-i`: (Optional) Inherited interfaces should be printed. (BOOLEAN,
+        false)
+
+    -   `-s`: (Optional) If a classname is specified, print its subclasses
+         in addition to its superclasses. Without this option only the
+         superclasses will be printed. (BOOLEAN, false)
+
+    *arguments*:
+
+    -   *classname*: (Optional) The name of the class whose hierarchy should be
+        printed. If not specified, all class hierarchies are printed. (STRING,
+        no default value)
+
+`VM.classes` \[*options*\]
+:   Print all loaded classes
+
+    Impact: Medium: Depends on number of loaded classes.
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-verbose`: (Optional) Dump the detailed content of a Java class.
+        Some classes are annotated with flags: `F` = has, or inherits, a non-empty finalize method,
+        `f` = has final method, `W` = methods rewritten, `C` = marked with `@Contended` annotation,
+        `R` = has been redefined, `S` = is shared class (BOOLEAN, false)
+
+`VM.classloader_stats`
+:   Print statistics about all ClassLoaders.
+
+    Impact: Low
+
+`VM.classloaders` \[*options*\]
+:   Prints classloader hierarchy.
+
+    Impact: Medium --- Depends on number of class loaders and classes loaded.
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `show-classes`: (Optional) Print loaded classes. (BOOLEAN, false)
+    -   `verbose`: (Optional) Print detailed information. (BOOLEAN, false)
+    -   `fold`: (Optional) Show loaders of the same name and class as one. (BOOLEAN, true)
+
+`VM.command_line`
+:   Print the command line used to start this VM instance.
+
+    Impact: Low
+
+`VM.dynlibs`
+:   Print loaded dynamic libraries.
+
+    Impact: Low
+
+`VM.events` \[*options*\]
+:   Print VM event logs
+
+    Impact: Low --- Depends on event log size.
+
+    *options*:
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    -   `log`: (Optional) Name of log to be printed.
+        If omitted, all logs are printed. (STRING, no default value)
+    -   `max`: (Optional) Maximum number of events to be printed (newest first).
+        If omitted, all events are printed. (STRING, no default value)
+
+`VM.flags` \[*options*\]
+:   Print the VM flag options and their current values.
+
+    Impact: Low
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-all`: (Optional) Prints all flags supported by the VM (BOOLEAN,
+        false).
+
+`VM.info`
+:   Print information about the JVM environment and status.
+
+    Impact: Low
+
+`VM.log` \[*options*\]
+:   Lists current log configuration, enables/disables/configures a log output,
+    or rotates all logs.
+
+    Impact: Low
+
+    *options*:
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    -   `output`: (Optional) The name or index (\#) of output to configure.
+        (STRING, no default value)
+
+    -   `output_options`: (Optional) Options for the output. (STRING, no
+        default value)
+
+    -   `what`: (Optional) Configures what tags to log. (STRING, no default
+        value )
+
+    -   `decorators`: (Optional) Configures which decorators to use. Use 'none'
+        or an empty value to remove all. (STRING, no default value)
+
+    -   `disable`: (Optional) Turns off all logging and clears the log
+        configuration. (BOOLEAN, no default value)
+
+    -   `list`: (Optional) Lists current log configuration. (BOOLEAN, no
+        default value)
+
+    -   `rotate`: (Optional) Rotates all logs. (BOOLEAN, no default value)
+
+`VM.metaspace`  \[*options*\]
+:   Prints the statistics for the metaspace
+
+    Impact: Medium --- Depends on number of classes loaded.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `basic`: (Optional) Prints a basic summary (does not need a safepoint). (BOOLEAN, false)
+    -   `show-loaders`: (Optional) Shows usage by class loader. (BOOLEAN, false)
+    -   `show-classes`: (Optional) If show-loaders is set, shows loaded classes for each loader. (BOOLEAN, false)
+    -   `by-chunktype`: (Optional) Break down numbers by chunk type. (BOOLEAN, false)
+    -   `by-spacetype`: (Optional) Break down numbers by loader type. (BOOLEAN, false)
+    -   `vslist`: (Optional) Shows details about the underlying virtual space. (BOOLEAN, false)
+    -   `chunkfreelist`: (Optional) Shows details about global chunk free lists (ChunkManager). (BOOLEAN, false)
+    -   `scale`: (Optional) Memory usage in which to scale. Valid values are: 1, KB, MB
+        or GB (fixed scale) or "dynamic" for a dynamically chosen scale. (STRING, dynamic)
+
+`VM.native_memory` \[*options*\]
+:   Print native memory usage
+
+    Impact: Medium
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `summary`: (Optional) Requests runtime to report current memory
+        summary, which includes total reserved and committed memory, along with
+        memory usage summary by each subsystem. (BOOLEAN, false)
+
+    -   `detail`: (Optional) Requests runtime to report memory allocation >=
+        1K by each callsite. (BOOLEAN, false)
+
+    -   `baseline`: (Optional) Requests runtime to baseline current memory
+        usage, so it can be compared against in later time. (BOOLEAN, false)
+
+    -   `summary.diff`: (Optional) Requests runtime to report memory summary
+        comparison against previous baseline. (BOOLEAN, false)
+
+    -   `detail.diff`: (Optional) Requests runtime to report memory detail
+        comparison against previous baseline, which shows the memory allocation
+        activities at different callsites. (BOOLEAN, false)
+
+    -   `statistics`: (Optional) Prints tracker statistics for tuning purpose.
+        (BOOLEAN, false)
+
+    -   `scale`: (Optional) Memory usage in which scale, KB, MB or GB (STRING,
+        KB)
+
+`VM.set_flag` \[*arguments*\]
+:   Sets VM flag option using the provided value.
+
+    Impact: Low
+
+    *arguments*:
+
+    -   *flag name*: The name of the flag that you want to set (STRING, no
+        default value)
+
+    -   *string value*: (Optional) The value that you want to set (STRING, no
+        default value)
+
+`VM.stringtable` \[*options*\]
+:   Dump string table.
+
+    Impact: Medium --- depends on the Java content.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-verbose`: (Optional) Dumps the content of each string in the table
+        (BOOLEAN, false)
+
+`VM.symboltable` \[*options*\]
+:   Dump symbol table.
+
+    Impact: Medium --- depends on the Java content.
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax).
+
+    *options*:
+
+    -   `-verbose`: (Optional) Dumps the content of each symbol in the table
+        (BOOLEAN, false)
+
+`VM.system_properties`
+:   Print system properties.
+
+    Impact: Low
+
+`VM.systemdictionary`
+:   Prints the statistics for dictionary hashtable sizes and bucket length.
+
+    Impact: Medium
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `verbose`: (Optional) Dump the content of each dictionary entry for all
+        class loaders (BOOLEAN, false) .
+
+`VM.uptime` \[*options*\]
+:   Print VM uptime.
+
+    Impact: Low
+
+    **Note:**
+
+    The following *options* must be specified using either *key* or
+    *key*`=`*value* syntax.
+
+    *options*:
+
+    -   `-date`: (Optional) Adds a prefix with the current date (BOOLEAN,
+        false)
+
+`VM.version`
+:   Print JVM version information.
+
+    Impact: Low
diff --git a/src/jdk.jcmd/share/man/jinfo.1 b/src/jdk.jcmd/share/man/jinfo.1
deleted file mode 100644
index 49d8a852633..00000000000
--- a/src/jdk.jcmd/share/man/jinfo.1
+++ /dev/null
@@ -1,103 +0,0 @@
-.\" Copyright (c) 2004, 2018, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JINFO" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jinfo - generate Java configuration information for a specified Java
-process
-.SH SYNOPSIS
-.PP
-\f[B]Note:\f[R] This command is experimental and unsupported.
-.PP
-\f[V]jinfo\f[R] [\f[I]option\f[R]] \f[I]pid\f[R]
-.TP
-\f[I]option\f[R]
-This represents the \f[V]jinfo\f[R] command-line options.
-See \f[B]Options for the jinfo Command\f[R].
-.TP
-\f[I]pid\f[R]
-The process ID for which the configuration information is to be printed.
-The process must be a Java process.
-To get a list of Java processes running on a machine, use either the
-\f[V]ps\f[R] command or, if the JVM processes are not running in a
-separate docker instance, the \f[B]jps\f[R] command.
-.SH DESCRIPTION
-.PP
-The \f[V]jinfo\f[R] command prints Java configuration information for a
-specified Java process.
-The configuration information includes Java system properties and JVM
-command-line flags.
-If the specified process is running on a 64-bit JVM, then you might need
-to specify the \f[V]-J-d64\f[R] option, for example:
-.RS
-.PP
-\f[V]jinfo -J-d64 -sysprops\f[R] \f[I]pid\f[R]
-.RE
-.PP
-This command is unsupported and might not be available in future
-releases of the JDK.
-In Windows Systems where \f[V]dbgeng.dll\f[R] is not present, the
-Debugging Tools for Windows must be installed to have these tools work.
-The \f[V]PATH\f[R] environment variable should contain the location of
-the \f[V]jvm.dll\f[R] that\[aq]s used by the target process or the
-location from which the core dump file was produced.
-.SH OPTIONS FOR THE JINFO COMMAND
-.PP
-\f[B]Note:\f[R]
-.PP
-If none of the following options are used, both the command-line flags
-and the system property name-value pairs are printed.
-.TP
-\f[V]-flag\f[R] \f[I]name\f[R]
-Prints the name and value of the specified command-line flag.
-.TP
-\f[V]-flag\f[R] [\f[V]+\f[R]|\f[V]-\f[R]]\f[I]name\f[R]
-Enables or disables the specified Boolean command-line flag.
-.TP
-\f[V]-flag\f[R] \f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R]
-Sets the specified command-line flag to the specified value.
-.TP
-\f[V]-flags\f[R]
-Prints command-line flags passed to the JVM.
-.TP
-\f[V]-sysprops\f[R]
-Prints Java system properties as name-value pairs.
-.TP
-\f[V]-h\f[R] or \f[V]-help\f[R]
-Prints a help message.
diff --git a/src/jdk.jcmd/share/man/jinfo.md b/src/jdk.jcmd/share/man/jinfo.md
new file mode 100644
index 00000000000..5e8603e0e08
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jinfo.md
@@ -0,0 +1,88 @@
+---
+# Copyright (c) 2004, 2018, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JINFO(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jinfo - generate Java configuration information for a specified Java process
+
+## Synopsis
+
+**Note:** This command is experimental and unsupported.
+
+`jinfo` \[*option*\] *pid*
+
+*option*
+:   This represents the `jinfo` command-line options. See [Options for the
+    jinfo Command].
+
+*pid*
+:   The process ID for which the configuration information is to be printed.
+    The process must be a Java process. To get a list of Java processes running
+    on a machine, use either the `ps` command or, if the JVM processes are not
+    running in a separate docker instance, the [jps](jps.html) command.
+
+## Description
+
+The `jinfo` command prints Java configuration information for a specified Java
+process. The configuration information includes Java system properties and JVM
+command-line flags. If the specified process is running on a 64-bit JVM, then
+you might need to specify the `-J-d64` option, for example:
+
+>   `jinfo -J-d64 -sysprops` *pid*
+
+This command is unsupported and might not be available in future releases of
+the JDK. In Windows Systems where `dbgeng.dll` is not present, the Debugging
+Tools for Windows must be installed to have these tools work. The `PATH`
+environment variable should contain the location of the `jvm.dll` that's used
+by the target process or the location from which the core dump file was
+produced.
+
+## Options for the jinfo Command
+
+**Note:**
+
+If none of the following options are used, both the command-line flags and the
+system property name-value pairs are printed.
+
+`-flag` *name*
+:   Prints the name and value of the specified command-line flag.
+
+`-flag` \[`+`\|`-`\]*name*
+:   Enables or disables the specified Boolean command-line flag.
+
+`-flag` *name*`=`*value*
+:   Sets the specified command-line flag to the specified value.
+
+`-flags`
+:   Prints command-line flags passed to the JVM.
+
+`-sysprops`
+:   Prints Java system properties as name-value pairs.
+
+`-h` or `-help`
+:   Prints a help message.
diff --git a/src/jdk.jcmd/share/man/jmap.1 b/src/jdk.jcmd/share/man/jmap.1
deleted file mode 100644
index 42831aa68ac..00000000000
--- a/src/jdk.jcmd/share/man/jmap.1
+++ /dev/null
@@ -1,106 +0,0 @@
-.\" Copyright (c) 2004, 2018, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JMAP" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jmap - print details of a specified process
-.SH SYNOPSIS
-.PP
-\f[B]Note:\f[R] This command is experimental and unsupported.
-.PP
-\f[V]jmap\f[R] [\f[I]options\f[R]] \f[I]pid\f[R]
-.TP
-\f[I]options\f[R]
-This represents the \f[V]jmap\f[R] command-line options.
-See \f[B]Options for the jmap Command\f[R].
-.TP
-\f[I]pid\f[R]
-The process ID for which the information specified by the
-\f[I]options\f[R] is to be printed.
-The process must be a Java process.
-To get a list of Java processes running on a machine, use either the
-\f[V]ps\f[R] command or, if the JVM processes are not running in a
-separate docker instance, the \f[B]jps\f[R] command.
-.SH DESCRIPTION
-.PP
-The \f[V]jmap\f[R] command prints details of a specified running
-process.
-.PP
-\f[B]Note:\f[R]
-.PP
-This command is unsupported and might not be available in future
-releases of the JDK.
-On Windows Systems where the \f[V]dbgeng.dll\f[R] file isn\[aq]t
-present, the Debugging Tools for Windows must be installed to make these
-tools work.
-The \f[V]PATH\f[R] environment variable should contain the location of
-the \f[V]jvm.dll\f[R] file that\[aq]s used by the target process or the
-location from which the core dump file was produced.
-.SH OPTIONS FOR THE JMAP COMMAND
-.TP
-\f[V]-clstats\f[R] \f[I]pid\f[R]
-Connects to a running process and prints class loader statistics of Java
-heap.
-.TP
-\f[V]-finalizerinfo\f[R] \f[I]pid\f[R]
-Connects to a running process and prints information on objects awaiting
-finalization.
-.TP
-\f[V]-histo\f[R][\f[V]:live\f[R]] \f[I]pid\f[R]
-Connects to a running process and prints a histogram of the Java object
-heap.
-If the \f[V]live\f[R] suboption is specified, it then counts only live
-objects.
-.TP
-\f[V]-dump:\f[R]\f[I]dump_options\f[R] \f[I]pid\f[R]
-Connects to a running process and dumps the Java heap.
-The \f[I]dump_options\f[R] include:
-.RS
-.IP \[bu] 2
-\f[V]live\f[R] --- When specified, dumps only the live objects; if not
-specified, then dumps all objects in the heap.
-.IP \[bu] 2
-\f[V]format=b\f[R] --- Dumps the Java heap in \f[V]hprof\f[R] binary
-format
-.IP \[bu] 2
-\f[V]file=\f[R]\f[I]filename\f[R] --- Dumps the heap to
-\f[I]filename\f[R]
-.PP
-Example: \f[V]jmap -dump:live,format=b,file=heap.bin\f[R] \f[I]pid\f[R]
-.RE
diff --git a/src/jdk.jcmd/share/man/jmap.md b/src/jdk.jcmd/share/man/jmap.md
new file mode 100644
index 00000000000..1f986f97fab
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jmap.md
@@ -0,0 +1,89 @@
+---
+# Copyright (c) 2004, 2018, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JMAP(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jmap - print details of a specified process
+
+## Synopsis
+
+**Note:** This command is experimental and unsupported.
+
+`jmap` \[*options*\] *pid*
+
+*options*
+:   This represents the `jmap` command-line options. See [Options for the jmap
+    Command].
+
+*pid*
+:   The process ID for which the information specified by the *options* is to
+    be printed. The process must be a Java process. To get a list of Java
+    processes running on a machine, use either the `ps` command or, if the JVM
+    processes are not running in a separate docker instance, the
+    [jps](jps.html) command.
+
+## Description
+
+The `jmap` command prints details of a specified running process.
+
+**Note:**
+
+This command is unsupported and might not be available in future releases of
+the JDK. On Windows Systems where the `dbgeng.dll` file isn't present, the
+Debugging Tools for Windows must be installed to make these tools work. The
+`PATH` environment variable should contain the location of the `jvm.dll` file
+that's used by the target process or the location from which the core dump file
+was produced.
+
+## Options for the jmap Command
+
+`-clstats` *pid*
+:   Connects to a running process and prints class loader statistics of Java
+    heap.
+
+`-finalizerinfo` *pid*
+:   Connects to a running process and prints information on objects awaiting
+    finalization.
+
+`-histo`\[`:live`\] *pid*
+:   Connects to a running process and prints a histogram of the Java object
+    heap. If the `live` suboption is specified, it then counts only live
+    objects.
+
+`-dump:`*dump\_options* *pid*
+:   Connects to a running process and dumps the Java heap. The *dump\_options*
+    include:
+
+    -   `live` --- When specified, dumps only the live objects; if not
+        specified, then dumps all objects in the heap.
+
+    -   `format=b` --- Dumps the Java heap in `hprof` binary format
+
+    -   `file=`*filename* --- Dumps the heap to *filename*
+
+    Example: `jmap -dump:live,format=b,file=heap.bin` *pid*
diff --git a/src/jdk.jcmd/share/man/jps.1 b/src/jdk.jcmd/share/man/jps.1
deleted file mode 100644
index cbc69872b60..00000000000
--- a/src/jdk.jcmd/share/man/jps.1
+++ /dev/null
@@ -1,235 +0,0 @@
-.\" Copyright (c) 2004, 2018, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JPS" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jps - list the instrumented JVMs on the target system
-.SH SYNOPSIS
-.PP
-\f[B]Note:\f[R] This command is experimental and unsupported.
-.PP
-\f[V]jps\f[R] [\f[V]-q\f[R]] [\f[V]-mlvV\f[R]] [\f[I]hostid\f[R]]
-.PP
-\f[V]jps\f[R] [\f[V]-help\f[R]]
-.SH OPTIONS
-.TP
-\f[V]-q\f[R]
-Suppresses the output of the class name, JAR file name, and arguments
-passed to the \f[V]main\f[R] method, producing a list of only local JVM
-identifiers.
-.TP
-\f[V]-mlvV\f[R]
-You can specify any combination of these options.
-.RS
-.IP \[bu] 2
-\f[V]-m\f[R] displays the arguments passed to the \f[V]main\f[R] method.
-The output may be \f[V]null\f[R] for embedded JVMs.
-.IP \[bu] 2
-\f[V]-l\f[R] displays the full package name for the application\[aq]s
-\f[V]main\f[R] class or the full path name to the application\[aq]s JAR
-file.
-.IP \[bu] 2
-\f[V]-v\f[R] displays the arguments passed to the JVM.
-.IP \[bu] 2
-\f[V]-V\f[R] suppresses the output of the class name, JAR file name, and
-arguments passed to the \f[V]main\f[R] method, producing a list of only
-local JVM identifiers.
-.RE
-.TP
-\f[I]hostid\f[R]
-The identifier of the host for which the process report should be
-generated.
-The \f[V]hostid\f[R] can include optional components that indicate the
-communications protocol, port number, and other implementation specific
-data.
-See \f[B]Host Identifier\f[R].
-.TP
-\f[V]-help\f[R]
-Displays the help message for the \f[V]jps\f[R] command.
-.SH DESCRIPTION
-.PP
-The \f[V]jps\f[R] command lists the instrumented Java HotSpot VMs on the
-target system.
-The command is limited to reporting information on JVMs for which it has
-the access permissions.
-.PP
-If the \f[V]jps\f[R] command is run without specifying a
-\f[V]hostid\f[R], then it searches for instrumented JVMs on the local
-host.
-If started with a \f[V]hostid\f[R], then it searches for JVMs on the
-indicated host, using the specified protocol and port.
-A \f[V]jstatd\f[R] process is assumed to be running on the target host.
-.PP
-The \f[V]jps\f[R] command reports the local JVM identifier, or
-\f[V]lvmid\f[R], for each instrumented JVM found on the target system.
-The \f[V]lvmid\f[R] is typically, but not necessarily, the operating
-system\[aq]s process identifier for the JVM process.
-With no options, the \f[V]jps\f[R] command lists each Java
-application\[aq]s \f[V]lvmid\f[R] followed by the short form of the
-application\[aq]s class name or jar file name.
-The short form of the class name or JAR file name omits the class\[aq]s
-package information or the JAR files path information.
-.PP
-The \f[V]jps\f[R] command uses the Java launcher to find the class name
-and arguments passed to the main method.
-If the target JVM is started with a custom launcher, then the class or
-JAR file name, and the arguments to the \f[V]main\f[R] method aren\[aq]t
-available.
-In this case, the \f[V]jps\f[R] command outputs the string
-\f[V]Unknown\f[R] for the class name, or JAR file name, and for the
-arguments to the \f[V]main\f[R] method.
-.PP
-The list of JVMs produced by the \f[V]jps\f[R] command can be limited by
-the permissions granted to the principal running the command.
-The command lists only the JVMs for which the principal has access
-rights as determined by operating system-specific access control
-mechanisms.
-.SH HOST IDENTIFIER
-.PP
-The host identifier, or \f[V]hostid\f[R], is a string that indicates the
-target system.
-The syntax of the \f[V]hostid\f[R] string corresponds to the syntax of a
-URI:
-.RS
-.PP
-[\f[I]protocol\f[R]\f[V]:\f[R]][[\f[V]//\f[R]]\f[I]hostname\f[R]][\f[V]:\f[R]\f[I]port\f[R]][\f[V]/\f[R]\f[I]servername\f[R]]
-.RE
-.TP
-\f[I]protocol\f[R]
-The communications protocol.
-If the \f[I]protocol\f[R] is omitted and a \f[I]hostname\f[R] isn\[aq]t
-specified, then the default protocol is a platform-specific, optimized,
-local protocol.
-If the protocol is omitted and a host name is specified, then the
-default protocol is \f[V]rmi\f[R].
-.TP
-\f[I]hostname\f[R]
-A host name or IP address that indicates the target host.
-If you omit the \f[I]hostname\f[R] parameter, then the target host is
-the local host.
-.TP
-\f[I]port\f[R]
-The default port for communicating with the remote server.
-If the \f[I]hostname\f[R] parameter is omitted or the \f[I]protocol\f[R]
-parameter specifies an optimized, local protocol, then the
-\f[I]port\f[R] parameter is ignored.
-Otherwise, treatment of the \f[I]port\f[R] parameter is
-implementation-specific.
-For the default \f[V]rmi\f[R] protocol, the \f[I]port\f[R] parameter
-indicates the port number for the \f[V]rmiregistry\f[R] on the remote
-host.
-If the \f[I]port\f[R] parameter is omitted, and the \f[I]protocol\f[R]
-parameter indicates \f[V]rmi\f[R], then the default
-\f[V]rmiregistry\f[R] port (\f[V]1099\f[R]) is used.
-.TP
-\f[I]servername\f[R]
-The treatment of this parameter depends on the implementation.
-For the optimized, local protocol, this field is ignored.
-For the \f[V]rmi\f[R] protocol, this parameter is a string that
-represents the name of the RMI remote object on the remote host.
-See the \f[B]jstatd\f[R] command \f[V]-n\f[R] option.
-.SH OUTPUT FORMAT OF THE JPS COMMAND
-.PP
-The output of the \f[V]jps\f[R] command has the following pattern:
-.RS
-.PP
-\f[I]lvmid\f[R] [ [ \f[I]classname\f[R] | \f[I]JARfilename\f[R] |
-\f[V]\[dq]Unknown\[dq]\f[R]] [ \f[I]arg\f[R]* ] [ \f[I]jvmarg\f[R]* ] ]
-.RE
-.PP
-All output tokens are separated by white space.
-An \f[V]arg\f[R] value that includes embedded white space introduces
-ambiguity when attempting to map arguments to their actual positional
-parameters.
-.PP
-\f[B]Note:\f[R]
-.PP
-It\[aq]s recommended that you don\[aq]t write scripts to parse
-\f[V]jps\f[R] output because the format might change in future releases.
-If you write scripts that parse \f[V]jps\f[R] output, then expect to
-modify them for future releases of this tool.
-.SH EXAMPLES
-.PP
-This section provides examples of the \f[V]jps\f[R] command.
-.PP
-List the instrumented JVMs on the local host:
-.IP
-.nf
-\f[CB]
-jps
-18027 Java2Demo.JAR
-18032 jps
-18005 jstat
-\f[R]
-.fi
-.PP
-The following example lists the instrumented JVMs on a remote host.
-This example assumes that the \f[V]jstat\f[R] server and either the its
-internal RMI registry or a separate external \f[V]rmiregistry\f[R]
-process are running on the remote host on the default port (port
-\f[V]1099\f[R]).
-It also assumes that the local host has appropriate permissions to
-access the remote host.
-This example includes the \f[V]-l\f[R] option to output the long form of
-the class names or JAR file names.
-.IP
-.nf
-\f[CB]
-jps -l remote.domain
-3002 /opt/jdk1.7.0/demo/jfc/Java2D/Java2Demo.JAR
-2857 sun.tools.jstatd.jstatd
-\f[R]
-.fi
-.PP
-The following example lists the instrumented JVMs on a remote host with
-a nondefault port for the RMI registry.
-This example assumes that the \f[V]jstatd\f[R] server, with an internal
-RMI registry bound to port \f[V]2002\f[R], is running on the remote
-host.
-This example also uses the \f[V]-m\f[R] option to include the arguments
-passed to the \f[V]main\f[R] method of each of the listed Java
-applications.
-.IP
-.nf
-\f[CB]
-jps -m remote.domain:2002
-3002 /opt/jdk1.7.0/demo/jfc/Java2D/Java2Demo.JAR
-3102 sun.tools.jstatd.jstatd -p 2002
-\f[R]
-.fi
diff --git a/src/jdk.jcmd/share/man/jps.md b/src/jdk.jcmd/share/man/jps.md
new file mode 100644
index 00000000000..be3994c411e
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jps.md
@@ -0,0 +1,189 @@
+---
+# Copyright (c) 2004, 2018, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JPS(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jps - list the instrumented JVMs on the target system
+
+## Synopsis
+
+**Note:** This command is experimental and unsupported.
+
+`jps` \[`-q`\] \[`-mlvV`\] \[*hostid*\]
+
+`jps` \[`-help`\]
+
+## Options
+
+`-q`
+:   Suppresses the output of the class name, JAR file name, and arguments
+    passed to the `main` method, producing a list of only local JVM
+    identifiers.
+
+`-mlvV`
+:   You can specify any combination of these options.
+
+    -   `-m` displays the arguments passed to the `main` method. The output may
+        be `null` for embedded JVMs.
+
+    -   `-l` displays the full package name for the application's `main` class
+        or the full path name to the application's JAR file.
+
+    -   `-v` displays the arguments passed to the JVM.
+
+    -   `-V` suppresses the output of the class name, JAR file name, and
+        arguments passed to the `main` method, producing a list of only local
+        JVM identifiers.
+
+*hostid*
+:   The identifier of the host for which the process report should be
+    generated. The `hostid` can include optional components that indicate the
+    communications protocol, port number, and other implementation specific
+    data. See [Host Identifier].
+
+`-help`
+:   Displays the help message for the `jps` command.
+
+## Description
+
+The `jps` command lists the instrumented Java HotSpot VMs on the target system.
+The command is limited to reporting information on JVMs for which it has the
+access permissions.
+
+If the `jps` command is run without specifying a `hostid`, then it searches for
+instrumented JVMs on the local host. If started with a `hostid`, then it
+searches for JVMs on the indicated host, using the specified protocol and port.
+A `jstatd` process is assumed to be running on the target host.
+
+The `jps` command reports the local JVM identifier, or `lvmid`, for each
+instrumented JVM found on the target system. The `lvmid` is typically, but not
+necessarily, the operating system's process identifier for the JVM process.
+With no options, the `jps` command lists each Java application's `lvmid`
+followed by the short form of the application's class name or jar file name.
+The short form of the class name or JAR file name omits the class's package
+information or the JAR files path information.
+
+The `jps` command uses the Java launcher to find the class name and arguments
+passed to the main method. If the target JVM is started with a custom launcher,
+then the class or JAR file name, and the arguments to the `main` method aren't
+available. In this case, the `jps` command outputs the string `Unknown` for the
+class name, or JAR file name, and for the arguments to the `main` method.
+
+The list of JVMs produced by the `jps` command can be limited by the
+permissions granted to the principal running the command. The command lists
+only the JVMs for which the principal has access rights as determined by
+operating system-specific access control mechanisms.
+
+## Host Identifier
+
+The host identifier, or `hostid`, is a string that indicates the target system.
+The syntax of the `hostid` string corresponds to the syntax of a URI:
+
+>   \[*protocol*`:`\]\[\[`//`\]*hostname*\]\[`:`*port*\]\[`/`*servername*\]
+
+*protocol*
+:   The communications protocol. If the *protocol* is omitted and a *hostname*
+    isn't specified, then the default protocol is a platform-specific,
+    optimized, local protocol. If the protocol is omitted and a host name is
+    specified, then the default protocol is `rmi`.
+
+*hostname*
+:   A host name or IP address that indicates the target host. If you omit the
+    *hostname* parameter, then the target host is the local host.
+
+*port*
+:   The default port for communicating with the remote server. If the
+    *hostname* parameter is omitted or the *protocol* parameter specifies an
+    optimized, local protocol, then the *port* parameter is ignored. Otherwise,
+    treatment of the *port* parameter is implementation-specific. For the
+    default `rmi` protocol, the *port* parameter indicates the port number for
+    the `rmiregistry` on the remote host. If the *port* parameter is omitted,
+    and the *protocol* parameter indicates `rmi`, then the default
+    `rmiregistry` port (`1099`) is used.
+
+*servername*
+:   The treatment of this parameter depends on the implementation. For the
+    optimized, local protocol, this field is ignored. For the `rmi` protocol,
+    this parameter is a string that represents the name of the RMI remote
+    object on the remote host. See the [jstatd](jstatd.html) command `-n`
+    option.
+
+## Output Format of the jps Command
+
+The output of the `jps` command has the following pattern:
+
+>   *lvmid* \[ \[ *classname* \| *JARfilename* \| `"Unknown"`\] \[ *arg*\* \]
+    \[ *jvmarg*\* \] \]
+
+All output tokens are separated by white space. An `arg` value that includes
+embedded white space introduces ambiguity when attempting to map arguments to
+their actual positional parameters.
+
+**Note:**
+
+It's recommended that you don't write scripts to parse `jps` output because the
+format might change in future releases. If you write scripts that parse `jps`
+output, then expect to modify them for future releases of this tool.
+
+## Examples
+
+This section provides examples of the `jps` command.
+
+List the instrumented JVMs on the local host:
+
+```
+jps
+18027 Java2Demo.JAR
+18032 jps
+18005 jstat
+```
+
+The following example lists the instrumented JVMs on a remote host. This
+example assumes that the `jstat` server and either the its internal RMI
+registry or a separate external `rmiregistry` process are running on the remote
+host on the default port (port `1099`). It also assumes that the local host has
+appropriate permissions to access the remote host. This example includes the
+`-l` option to output the long form of the class names or JAR file names.
+
+```
+jps -l remote.domain
+3002 /opt/jdk1.7.0/demo/jfc/Java2D/Java2Demo.JAR
+2857 sun.tools.jstatd.jstatd
+```
+
+The following example lists the instrumented JVMs on a remote host with a
+nondefault port for the RMI registry. This example assumes that the `jstatd`
+server, with an internal RMI registry bound to port `2002`, is running on the
+remote host. This example also uses the `-m` option to include the arguments
+passed to the `main` method of each of the listed Java applications.
+
+```
+jps -m remote.domain:2002
+3002 /opt/jdk1.7.0/demo/jfc/Java2D/Java2Demo.JAR
+3102 sun.tools.jstatd.jstatd -p 2002
+```
diff --git a/src/jdk.jcmd/share/man/jstack.1 b/src/jdk.jcmd/share/man/jstack.1
deleted file mode 100644
index 933db5fc80d..00000000000
--- a/src/jdk.jcmd/share/man/jstack.1
+++ /dev/null
@@ -1,89 +0,0 @@
-.\" Copyright (c) 2004, 2018, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JSTACK" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jstack - print Java stack traces of Java threads for a specified Java
-process
-.SH SYNOPSIS
-.PP
-\f[B]Note:\f[R] This command is experimental and unsupported.
-.PP
-\f[V]jstack\f[R] [\f[I]options\f[R]] \f[I]pid\f[R]
-.TP
-\f[I]options\f[R]
-This represents the \f[V]jstack\f[R] command-line options.
-See \f[B]Options for the jstack Command\f[R].
-.TP
-\f[I]pid\f[R]
-The process ID for which the stack trace is printed.
-The process must be a Java process.
-To get a list of Java processes running on a machine, use either the
-\f[V]ps\f[R] command or, if the JVM processes are not running in a
-separate docker instance, the \f[B]jps\f[R] command.
-.SH DESCRIPTION
-.PP
-The \f[V]jstack\f[R] command prints Java stack traces of Java threads
-for a specified Java process.
-For each Java frame, the full class name, method name, byte code index
-(BCI), and line number, when available, are printed.
-C++ mangled names aren\[aq]t demangled.
-To demangle C++ names, the output of this command can be piped to
-\f[V]c++filt\f[R].
-When the specified process is running on a 64-bit JVM, you might need to
-specify the \f[V]-J-d64\f[R] option, for example:
-\f[V]jstack -J-d64\f[R] \f[I]pid\f[R].
-.PP
-\f[B]Note:\f[R]
-.PP
-This command is unsupported and might not be available in future
-releases of the JDK.
-In Windows Systems where the \f[V]dbgeng.dll\f[R] file isn\[aq]t
-present, the Debugging Tools for Windows must be installed so that these
-tools work.
-The \f[V]PATH\f[R] environment variable needs to contain the location of
-the \f[V]jvm.dll\f[R] that is used by the target process, or the
-location from which the core dump file was produced.
-.SH OPTIONS FOR THE JSTACK COMMAND
-.TP
-\f[V]-l\f[R]
-The long listing option prints additional information about locks.
-.TP
-\f[V]-h\f[R] or \f[V]-help\f[R]
-Prints a help message.
diff --git a/src/jdk.jcmd/share/man/jstack.md b/src/jdk.jcmd/share/man/jstack.md
new file mode 100644
index 00000000000..84df235a70e
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jstack.md
@@ -0,0 +1,73 @@
+---
+# Copyright (c) 2004, 2018, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JSTACK(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jstack - print Java stack traces of Java threads for a specified Java process
+
+## Synopsis
+
+**Note:** This command is experimental and unsupported.
+
+`jstack` \[*options*\] *pid*
+
+*options*
+:   This represents the `jstack` command-line options. See [Options for the
+    jstack Command].
+
+*pid*
+:   The process ID for which the stack trace is printed. The process must be a
+    Java process. To get a list of Java processes running on a machine, use
+    either the `ps` command or, if the JVM processes are not running in a
+    separate docker instance, the [jps](jps.html) command.
+
+## Description
+
+The `jstack` command prints Java stack traces of Java threads for a specified
+Java process. For each Java frame, the full class name, method name, byte code
+index (BCI), and line number, when available, are printed. C++ mangled names
+aren't demangled. To demangle C++ names, the output of this command can be
+piped to `c++filt`. When the specified process is running on a 64-bit JVM, you
+might need to specify the `-J-d64` option, for example: `jstack -J-d64` *pid*.
+
+**Note:**
+
+This command is unsupported and might not be available in future releases of
+the JDK. In Windows Systems where the `dbgeng.dll` file isn't present, the
+Debugging Tools for Windows must be installed so that these tools work. The
+`PATH` environment variable needs to contain the location of the `jvm.dll` that
+is used by the target process, or the location from which the core dump file
+was produced.
+
+## Options for the jstack Command
+
+`-l`
+:   The long listing option prints additional information about locks.
+
+`-h` or `-help`
+:   Prints a help message.
diff --git a/src/jdk.jcmd/share/man/jstat.1 b/src/jdk.jcmd/share/man/jstat.1
deleted file mode 100644
index 22e111a812b..00000000000
--- a/src/jdk.jcmd/share/man/jstat.1
+++ /dev/null
@@ -1,689 +0,0 @@
-.\" Copyright (c) 2004, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JSTAT" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jstat - monitor JVM statistics
-.SH SYNOPSIS
-.PP
-\f[B]Note:\f[R] This command is experimental and unsupported.
-.PP
-\f[V]jstat\f[R] \f[I]generalOptions\f[R]
-.PP
-\f[V]jstat\f[R] \f[I]outputOptions\f[R] [\f[V]-t\f[R]] [\f[V]-h\f[R]
-\f[I]lines\f[R]] \f[I]vmid\f[R] [\f[I]interval\f[R] [\f[I]count\f[R]]]
-.TP
-\f[I]generalOptions\f[R]
-A single general command-line option.
-See \f[B]General Options\f[R].
-.TP
-\f[I]outputOptions\f[R]
-An option reported by the \f[V]-options\f[R] option.
-One or more output options that consist of a single
-\f[V]statOption\f[R], plus any of the \f[V]-t\f[R], \f[V]-h\f[R], and
-\f[V]-J\f[R] options.
-See \f[B]Output Options for the jstat Command\f[R].
-.TP
-\f[V]-t\f[R]
-Displays a time-stamp column as the first column of output.
-The time stamp is the time since the start time of the target JVM.
-.TP
-\f[V]-h\f[R] \f[I]n\f[R]
-Displays a column header every \f[I]n\f[R] samples (output rows), where
-\f[I]n\f[R] is a positive integer.
-The default value is \f[V]0\f[R], which displays the column header of
-the first row of data.
-.TP
-\f[I]vmid\f[R]
-A virtual machine identifier, which is a string that indicates the
-target JVM.
-See \f[B]Virtual Machine Identifier\f[R].
-.TP
-\f[I]interval\f[R]
-The sampling interval in the specified units, seconds (s) or
-milliseconds (ms).
-Default units are milliseconds.
-This must be a positive integer.
-When specified, the \f[V]jstat\f[R] command produces its output at each
-interval.
-.TP
-\f[I]count\f[R]
-The number of samples to display.
-The default value is infinity, which causes the \f[V]jstat\f[R] command
-to display statistics until the target JVM terminates or the
-\f[V]jstat\f[R] command is terminated.
-This value must be a positive integer.
-.SH DESCRIPTION
-.PP
-The \f[V]jstat\f[R] command displays performance statistics for an
-instrumented Java HotSpot VM.
-The target JVM is identified by its virtual machine identifier, or
-\f[V]vmid\f[R] option.
-.PP
-The \f[V]jstat\f[R] command supports two types of options, general
-options and output options.
-General options cause the \f[V]jstat\f[R] command to display simple
-usage and version information.
-Output options determine the content and format of the statistical
-output.
-.PP
-All options and their functionality are subject to change or removal in
-future releases.
-.SH GENERAL OPTIONS
-.PP
-If you specify one of the general options, then you can\[aq]t specify
-any other option or parameter.
-.TP
-\f[V]-help\f[R]
-Displays a help message.
-.TP
-\f[V]-options\f[R]
-Displays a list of static options.
-See \f[B]Output Options for the jstat Command\f[R].
-.SH OUTPUT OPTIONS FOR THE JSTAT COMMAND
-.PP
-If you don\[aq]t specify a general option, then you can specify output
-options.
-Output options determine the content and format of the \f[V]jstat\f[R]
-command\[aq]s output, and consist of a single \f[V]statOption\f[R], plus
-any of the other output options (\f[V]-h\f[R], \f[V]-t\f[R], and
-\f[V]-J\f[R]).
-The \f[V]statOption\f[R] must come first.
-.PP
-Output is formatted as a table, with columns that are separated by
-spaces.
-A header row with titles describes the columns.
-Use the \f[V]-h\f[R] option to set the frequency at which the header is
-displayed.
-Column header names are consistent among the different options.
-In general, if two options provide a column with the same name, then the
-data source for the two columns is the same.
-.PP
-Use the \f[V]-t\f[R] option to display a time-stamp column, labeled
-Timestamp as the first column of output.
-The Timestamp column contains the elapsed time, in seconds, since the
-target JVM started.
-The resolution of the time stamp is dependent on various factors and is
-subject to variation due to delayed thread scheduling on heavily loaded
-systems.
-.PP
-Use the interval and count parameters to determine how frequently and
-how many times, respectively, the \f[V]jstat\f[R] command displays its
-output.
-.PP
-\f[B]Note:\f[R]
-.PP
-Don\[aq]t write scripts to parse the \f[V]jstat\f[R] command\[aq]s
-output because the format might change in future releases.
-If you write scripts that parse the \f[V]jstat\f[R] command output, then
-expect to modify them for future releases of this tool.
-.TP
-\f[V]-statOption\f[R]
-Determines the statistics information that the \f[V]jstat\f[R] command
-displays.
-The following lists the available options.
-Use the \f[V]-options\f[R] general option to display the list of options
-for a particular platform installation.
-See \f[B]Stat Options and Output\f[R].
-.RS
-.PP
-\f[V]class\f[R]: Displays statistics about the behavior of the class
-loader.
-.PP
-\f[V]compiler\f[R]: Displays statistics about the behavior of the Java
-HotSpot VM Just-in-Time compiler.
-.PP
-\f[V]gc\f[R]: Displays statistics about the behavior of the garbage
-collected heap.
-.PP
-\f[V]gccapacity\f[R]: Displays statistics about the capacities of the
-generations and their corresponding spaces.
-.PP
-\f[V]gccause\f[R]: Displays a summary about garbage collection
-statistics (same as \f[V]-gcutil\f[R]), with the cause of the last and
-current (when applicable) garbage collection events.
-.PP
-\f[V]gcnew\f[R]: Displays statistics about the behavior of the new
-generation.
-.PP
-\f[V]gcnewcapacity\f[R]: Displays statistics about the sizes of the new
-generations and their corresponding spaces.
-.PP
-\f[V]gcold\f[R]: Displays statistics about the behavior of the old
-generation and metaspace statistics.
-.PP
-\f[V]gcoldcapacity\f[R]: Displays statistics about the sizes of the old
-generation.
-.PP
-\f[V]gcmetacapacity\f[R]: Displays statistics about the sizes of the
-metaspace.
-.PP
-\f[V]gcutil\f[R]: Displays a summary about garbage collection
-statistics.
-.PP
-\f[V]printcompilation\f[R]: Displays Java HotSpot VM compilation method
-statistics.
-.RE
-.TP
-\f[V]-J\f[R]\f[I]javaOption\f[R]
-Passes \f[I]javaOption\f[R] to the Java application launcher.
-For example, \f[V]-J-Xms48m\f[R] sets the startup memory to 48 MB.
-For a complete list of options, see \f[B]java\f[R].
-.SH STAT OPTIONS AND OUTPUT
-.PP
-The following information summarizes the columns that the
-\f[V]jstat\f[R] command outputs for each \f[I]statOption\f[R].
-.TP
-\f[V]-class\f[R] \f[I]option\f[R]
-Class loader statistics.
-.RS
-.PP
-\f[V]Loaded\f[R]: Number of classes loaded.
-.PP
-\f[V]Bytes\f[R]: Number of KB loaded.
-.PP
-\f[V]Unloaded\f[R]: Number of classes unloaded.
-.PP
-\f[V]Bytes\f[R]: Number of KB unloaded.
-.PP
-\f[V]Time\f[R]: Time spent performing class loading and unloading
-operations.
-.RE
-.TP
-\f[V]-compiler\f[R] \f[I]option\f[R]
-Java HotSpot VM Just-in-Time compiler statistics.
-.RS
-.PP
-\f[V]Compiled\f[R]: Number of compilation tasks performed.
-.PP
-\f[V]Failed\f[R]: Number of compilations tasks failed.
-.PP
-\f[V]Invalid\f[R]: Number of compilation tasks that were invalidated.
-.PP
-\f[V]Time\f[R]: Time spent performing compilation tasks.
-.PP
-\f[V]FailedType\f[R]: Compile type of the last failed compilation.
-.PP
-\f[V]FailedMethod\f[R]: Class name and method of the last failed
-compilation.
-.RE
-.TP
-\f[V]-gc\f[R] \f[I]option\f[R]
-Garbage collected heap statistics.
-.RS
-.PP
-\f[V]S0C\f[R]: Current survivor space 0 capacity (KB).
-.PP
-\f[V]S1C\f[R]: Current survivor space 1 capacity (KB).
-.PP
-\f[V]S0U\f[R]: Survivor space 0 utilization (KB).
-.PP
-\f[V]S1U\f[R]: Survivor space 1 utilization (KB).
-.PP
-\f[V]EC\f[R]: Current eden space capacity (KB).
-.PP
-\f[V]EU\f[R]: Eden space utilization (KB).
-.PP
-\f[V]OC\f[R]: Current old space capacity (KB).
-.PP
-\f[V]OU\f[R]: Old space utilization (KB).
-.PP
-\f[V]MC\f[R]: Metaspace Committed Size (KB).
-.PP
-\f[V]MU\f[R]: Metaspace utilization (KB).
-.PP
-\f[V]CCSC\f[R]: Compressed class committed size (KB).
-.PP
-\f[V]CCSU\f[R]: Compressed class space used (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation garbage collection (GC)
-events.
-.PP
-\f[V]YGCT\f[R]: Young generation garbage collection time.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.PP
-\f[V]FGCT\f[R]: Full garbage collection time.
-.PP
-\f[V]GCT\f[R]: Total garbage collection time.
-.RE
-.TP
-\f[V]-gccapacity\f[R] \f[I]option\f[R]
-Memory pool generation and space capacities.
-.RS
-.PP
-\f[V]NGCMN\f[R]: Minimum new generation capacity (KB).
-.PP
-\f[V]NGCMX\f[R]: Maximum new generation capacity (KB).
-.PP
-\f[V]NGC\f[R]: Current new generation capacity (KB).
-.PP
-\f[V]S0C\f[R]: Current survivor space 0 capacity (KB).
-.PP
-\f[V]S1C\f[R]: Current survivor space 1 capacity (KB).
-.PP
-\f[V]EC\f[R]: Current eden space capacity (KB).
-.PP
-\f[V]OGCMN\f[R]: Minimum old generation capacity (KB).
-.PP
-\f[V]OGCMX\f[R]: Maximum old generation capacity (KB).
-.PP
-\f[V]OGC\f[R]: Current old generation capacity (KB).
-.PP
-\f[V]OC\f[R]: Current old space capacity (KB).
-.PP
-\f[V]MCMN\f[R]: Minimum metaspace capacity (KB).
-.PP
-\f[V]MCMX\f[R]: Maximum metaspace capacity (KB).
-.PP
-\f[V]MC\f[R]: Metaspace Committed Size (KB).
-.PP
-\f[V]CCSMN\f[R]: Compressed class space minimum capacity (KB).
-.PP
-\f[V]CCSMX\f[R]: Compressed class space maximum capacity (KB).
-.PP
-\f[V]CCSC\f[R]: Compressed class committed size (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.RE
-.TP
-\f[V]-gccause\f[R] \f[I]option\f[R]
-This option displays the same summary of garbage collection statistics
-as the \f[V]-gcutil\f[R] option, but includes the causes of the last
-garbage collection event and (when applicable), the current garbage
-collection event.
-In addition to the columns listed for \f[V]-gcutil\f[R], this option
-adds the following columns:
-.RS
-.PP
-\f[V]LGCC\f[R]: Cause of last garbage collection
-.PP
-\f[V]GCC\f[R]: Cause of current garbage collection
-.RE
-.TP
-\f[V]-gcnew\f[R] \f[I]option\f[R]
-New generation statistics.
-.RS
-.PP
-\f[V]S0C\f[R]: Current survivor space 0 capacity (KB).
-.PP
-\f[V]S1C\f[R]: Current survivor space 1 capacity (KB).
-.PP
-\f[V]S0U\f[R]: Survivor space 0 utilization (KB).
-.PP
-\f[V]S1U\f[R]: Survivor space 1 utilization (KB).
-.PP
-\f[V]TT\f[R]: Tenuring threshold.
-.PP
-\f[V]MTT\f[R]: Maximum tenuring threshold.
-.PP
-\f[V]DSS\f[R]: Desired survivor size (KB).
-.PP
-\f[V]EC\f[R]: Current eden space capacity (KB).
-.PP
-\f[V]EU\f[R]: Eden space utilization (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]YGCT\f[R]: Young generation garbage collection time.
-.RE
-.TP
-\f[V]-gcnewcapacity\f[R] \f[I]option\f[R]
-New generation space size statistics.
-.RS
-.PP
-\f[V]NGCMN\f[R]: Minimum new generation capacity (KB).
-.PP
-\f[V]NGCMX\f[R]: Maximum new generation capacity (KB).
-.PP
-\f[V]NGC\f[R]: Current new generation capacity (KB).
-.PP
-\f[V]S0CMX\f[R]: Maximum survivor space 0 capacity (KB).
-.PP
-\f[V]S0C\f[R]: Current survivor space 0 capacity (KB).
-.PP
-\f[V]S1CMX\f[R]: Maximum survivor space 1 capacity (KB).
-.PP
-\f[V]S1C\f[R]: Current survivor space 1 capacity (KB).
-.PP
-\f[V]ECMX\f[R]: Maximum eden space capacity (KB).
-.PP
-\f[V]EC\f[R]: Current eden space capacity (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.RE
-.TP
-\f[V]-gcold\f[R] \f[I]option\f[R]
-Old generation size statistics.
-.RS
-.PP
-\f[V]MC\f[R]: Metaspace Committed Size (KB).
-.PP
-\f[V]MU\f[R]: Metaspace utilization (KB).
-.PP
-\f[V]CCSC\f[R]: Compressed class committed size (KB).
-.PP
-\f[V]CCSU\f[R]: Compressed class space used (KB).
-.PP
-\f[V]OC\f[R]: Current old space capacity (KB).
-.PP
-\f[V]OU\f[R]: Old space utilization (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.PP
-\f[V]FGCT\f[R]: Full garbage collection time.
-.PP
-\f[V]GCT\f[R]: Total garbage collection time.
-.RE
-.TP
-\f[V]-gcoldcapacity\f[R] \f[I]option\f[R]
-Old generation statistics.
-.RS
-.PP
-\f[V]OGCMN\f[R]: Minimum old generation capacity (KB).
-.PP
-\f[V]OGCMX\f[R]: Maximum old generation capacity (KB).
-.PP
-\f[V]OGC\f[R]: Current old generation capacity (KB).
-.PP
-\f[V]OC\f[R]: Current old space capacity (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.PP
-\f[V]FGCT\f[R]: Full garbage collection time.
-.PP
-\f[V]GCT\f[R]: Total garbage collection time.
-.RE
-.TP
-\f[V]-gcmetacapacity\f[R] \f[I]option\f[R]
-Metaspace size statistics.
-.RS
-.PP
-\f[V]MCMN\f[R]: Minimum metaspace capacity (KB).
-.PP
-\f[V]MCMX\f[R]: Maximum metaspace capacity (KB).
-.PP
-\f[V]MC\f[R]: Metaspace Committed Size (KB).
-.PP
-\f[V]CCSMN\f[R]: Compressed class space minimum capacity (KB).
-.PP
-\f[V]CCSMX\f[R]: Compressed class space maximum capacity (KB).
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.PP
-\f[V]FGCT\f[R]: Full garbage collection time.
-.PP
-\f[V]GCT\f[R]: Total garbage collection time.
-.RE
-.TP
-\f[V]-gcutil\f[R] \f[I]option\f[R]
-Summary of garbage collection statistics.
-.RS
-.PP
-\f[V]S0\f[R]: Survivor space 0 utilization as a percentage of the
-space\[aq]s current capacity.
-.PP
-\f[V]S1\f[R]: Survivor space 1 utilization as a percentage of the
-space\[aq]s current capacity.
-.PP
-\f[V]E\f[R]: Eden space utilization as a percentage of the space\[aq]s
-current capacity.
-.PP
-\f[V]O\f[R]: Old space utilization as a percentage of the space\[aq]s
-current capacity.
-.PP
-\f[V]M\f[R]: Metaspace utilization as a percentage of the space\[aq]s
-current capacity.
-.PP
-\f[V]CCS\f[R]: Compressed class space utilization as a percentage.
-.PP
-\f[V]YGC\f[R]: Number of young generation GC events.
-.PP
-\f[V]YGCT\f[R]: Young generation garbage collection time.
-.PP
-\f[V]FGC\f[R]: Number of full GC events.
-.PP
-\f[V]FGCT\f[R]: Full garbage collection time.
-.PP
-\f[V]GCT\f[R]: Total garbage collection time.
-.RE
-.TP
-\f[V]-printcompilation\f[R] \f[I]option\f[R]
-Java HotSpot VM compiler method statistics.
-.RS
-.PP
-\f[V]Compiled\f[R]: Number of compilation tasks performed by the most
-recently compiled method.
-.PP
-\f[V]Size\f[R]: Number of bytes of byte code of the most recently
-compiled method.
-.PP
-\f[V]Type\f[R]: Compilation type of the most recently compiled method.
-.PP
-\f[V]Method\f[R]: Class name and method name identifying the most
-recently compiled method.
-Class name uses a slash (/) instead of a dot (.)
-as a name space separator.
-The method name is the method within the specified class.
-The format for these two fields is consistent with the HotSpot
-\f[V]-XX:+PrintCompilation\f[R] option.
-.RE
-.SH VIRTUAL MACHINE IDENTIFIER
-.PP
-The syntax of the \f[V]vmid\f[R] string corresponds to the syntax of a
-URI:
-.RS
-.PP
-[\f[I]protocol\f[R]\f[V]:\f[R]][\f[V]//\f[R]]\f[I]lvmid\f[R][\f[V]\[at]\f[R]\f[I]hostname\f[R][\f[V]:\f[R]\f[I]port\f[R]][\f[V]/\f[R]\f[I]servername\f[R]]
-.RE
-.PP
-The syntax of the \f[V]vmid\f[R] string corresponds to the syntax of a
-URI.
-The \f[V]vmid\f[R] string can vary from a simple integer that represents
-a local JVM to a more complex construction that specifies a
-communications protocol, port number, and other implementation-specific
-values.
-.TP
-\f[I]protocol\f[R]
-The communications protocol.
-If the \f[I]protocol\f[R] value is omitted and a host name isn\[aq]t
-specified, then the default protocol is a platform-specific optimized
-local protocol.
-If the \f[I]protocol\f[R] value is omitted and a host name is specified,
-then the default protocol is \f[V]rmi\f[R].
-.TP
-\f[I]lvmid\f[R]
-The local virtual machine identifier for the target JVM.
-The \f[I]lvmid\f[R] is a platform-specific value that uniquely
-identifies a JVM on a system.
-The \f[I]lvmid\f[R] is the only required component of a virtual machine
-identifier.
-The \f[I]lvmid\f[R] is typically, but not necessarily, the operating
-system\[aq]s process identifier for the target JVM process.
-You can use the \f[V]jps\f[R] command to determine the \f[I]lvmid\f[R]
-provided the JVM processes is not running in a separate docker instance.
-You can also determine the \f[I]lvmid\f[R] on Linux and macOS platforms
-with the \f[V]ps\f[R] command, and on Windows with the Windows Task
-Manager.
-.TP
-\f[I]hostname\f[R]
-A host name or IP address that indicates the target host.
-If the \f[I]hostname\f[R] value is omitted, then the target host is the
-local host.
-.TP
-\f[I]port\f[R]
-The default port for communicating with the remote server.
-If the \f[I]hostname\f[R] value is omitted or the \f[I]protocol\f[R]
-value specifies an optimized, local protocol, then the \f[I]port\f[R]
-value is ignored.
-Otherwise, treatment of the \f[I]port\f[R] parameter is
-implementation-specific.
-For the default \f[V]rmi\f[R] protocol, the port value indicates the
-port number for the \f[V]rmiregistry\f[R] on the remote host.
-If the \f[I]port\f[R] value is omitted and the \f[I]protocol\f[R] value
-indicates \f[V]rmi\f[R], then the default rmiregistry port (1099) is
-used.
-.TP
-\f[I]servername\f[R]
-The treatment of the \f[I]servername\f[R] parameter depends on
-implementation.
-For the optimized local protocol, this field is ignored.
-For the \f[V]rmi\f[R] protocol, it represents the name of the RMI remote
-object on the remote host.
-.SH EXAMPLES
-.PP
-This section presents some examples of monitoring a local JVM with an
-\f[I]lvmid\f[R] of 21891.
-.SH THE GCUTIL OPTION
-.PP
-This example attaches to lvmid 21891 and takes 7 samples at 250
-millisecond intervals and displays the output as specified by the
-\f[V]-gcutil\f[R] option.
-.PP
-The output of this example shows that a young generation collection
-occurred between the third and fourth sample.
-The collection took 0.078 seconds and promoted objects from the eden
-space (E) to the old space (O), resulting in an increase of old space
-utilization from 66.80% to 68.19%.
-Before the collection, the survivor space was 97.02% utilized, but after
-this collection it\[aq]s 91.03% utilized.
-.IP
-.nf
-\f[CB]
-jstat -gcutil 21891 250 7
-  S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT     GCT
-  0.00  97.02  70.31  66.80  95.52  89.14      7    0.300     0    0.000    0.300
-  0.00  97.02  86.23  66.80  95.52  89.14      7    0.300     0    0.000    0.300
-  0.00  97.02  96.53  66.80  95.52  89.14      7    0.300     0    0.000    0.300
- 91.03   0.00   1.98  68.19  95.89  91.24      8    0.378     0    0.000    0.378
- 91.03   0.00  15.82  68.19  95.89  91.24      8    0.378     0    0.000    0.378
- 91.03   0.00  17.80  68.19  95.89  91.24      8    0.378     0    0.000    0.378
- 91.03   0.00  17.80  68.19  95.89  91.24      8    0.378     0    0.000    0.378
-\f[R]
-.fi
-.SH REPEAT THE COLUMN HEADER STRING
-.PP
-This example attaches to lvmid 21891 and takes samples at 250
-millisecond intervals and displays the output as specified by
-\f[V]-gcnew\f[R] option.
-In addition, it uses the \f[V]-h3\f[R] option to output the column
-header after every 3 lines of data.
-.PP
-In addition to showing the repeating header string, this example shows
-that between the second and third samples, a young GC occurred.
-Its duration was 0.001 seconds.
-The collection found enough active data that the survivor space 0
-utilization (S0U) would have exceeded the desired survivor size (DSS).
-As a result, objects were promoted to the old generation (not visible in
-this output), and the tenuring threshold (TT) was lowered from 31 to 2.
-.PP
-Another collection occurs between the fifth and sixth samples.
-This collection found very few survivors and returned the tenuring
-threshold to 31.
-.IP
-.nf
-\f[CB]
-jstat -gcnew -h3 21891 250
- S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
-  64.0   64.0    0.0   31.7 31  31   32.0    512.0    178.6    249    0.203
-  64.0   64.0    0.0   31.7 31  31   32.0    512.0    355.5    249    0.203
-  64.0   64.0   35.4    0.0  2  31   32.0    512.0     21.9    250    0.204
- S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
-  64.0   64.0   35.4    0.0  2  31   32.0    512.0    245.9    250    0.204
-  64.0   64.0   35.4    0.0  2  31   32.0    512.0    421.1    250    0.204
-  64.0   64.0    0.0   19.0 31  31   32.0    512.0     84.4    251    0.204
- S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
-  64.0   64.0    0.0   19.0 31  31   32.0    512.0    306.7    251    0.204
-\f[R]
-.fi
-.SH INCLUDE A TIME STAMP FOR EACH SAMPLE
-.PP
-This example attaches to lvmid 21891 and takes 3 samples at 250
-millisecond intervals.
-The \f[V]-t\f[R] option is used to generate a time stamp for each sample
-in the first column.
-.PP
-The Timestamp column reports the elapsed time in seconds since the start
-of the target JVM.
-In addition, the \f[V]-gcoldcapacity\f[R] output shows the old
-generation capacity (OGC) and the old space capacity (OC) increasing as
-the heap expands to meet allocation or promotion demands.
-The old generation capacity (OGC) has grown from 11,696 KB to 13,820 KB
-after the eighty-first full garbage collection (FGC).
-The maximum capacity of the generation (and space) is 60,544 KB (OGCMX),
-so it still has room to expand.
-.IP
-.nf
-\f[CB]
-Timestamp      OGCMN    OGCMX     OGC       OC       YGC   FGC    FGCT    GCT
-          150.1   1408.0  60544.0  11696.0  11696.0   194    80    2.874   3.799
-          150.4   1408.0  60544.0  13820.0  13820.0   194    81    2.938   3.863
-          150.7   1408.0  60544.0  13820.0  13820.0   194    81    2.938   3.863
-\f[R]
-.fi
-.SH MONITOR INSTRUMENTATION FOR A REMOTE JVM
-.PP
-This example attaches to lvmid 40496 on the system named
-\f[V]remote.domain\f[R] using the \f[V]-gcutil\f[R] option, with samples
-taken every second indefinitely.
-.PP
-The lvmid is combined with the name of the remote host to construct a
-vmid of \f[V]40496\[at]remote.domain\f[R].
-This vmid results in the use of the \f[V]rmi\f[R] protocol to
-communicate to the default \f[V]jstatd\f[R] server on the remote host.
-The \f[V]jstatd\f[R] server is located using the \f[V]rmiregistry\f[R]
-command on \f[V]remote.domain\f[R] that\[aq]s bound to the default port
-of the \f[V]rmiregistry\f[R] command (port 1099).
-.IP
-.nf
-\f[CB]
-jstat -gcutil 40496\[at]remote.domain 1000
-\&... output omitted
-\f[R]
-.fi
diff --git a/src/jdk.jcmd/share/man/jstat.md b/src/jdk.jcmd/share/man/jstat.md
new file mode 100644
index 00000000000..795fc9caa40
--- /dev/null
+++ b/src/jdk.jcmd/share/man/jstat.md
@@ -0,0 +1,588 @@
+---
+# Copyright (c) 2004, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JSTAT(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jstat - monitor JVM statistics
+
+## Synopsis
+
+**Note:** This command is experimental and unsupported.
+
+`jstat` *generalOptions*
+
+`jstat` *outputOptions* \[`-t`\] \[`-h` *lines*\] *vmid* \[*interval*
+\[*count*\]\]
+
+*generalOptions*
+:   A single general command-line option. See [General Options].
+
+*outputOptions*
+:   An option reported by the `-options` option. One or more output options
+    that consist of a single `statOption`, plus any of the `-t`, `-h`, and `-J`
+    options. See [Output Options for the jstat Command].
+
+`-t`
+:   Displays a time-stamp column as the first column of output. The time stamp
+    is the time since the start time of the target JVM.
+
+`-h` *n*
+:   Displays a column header every *n* samples (output rows), where *n* is a
+    positive integer. The default value is `0`, which displays the column
+    header of the first row of data.
+
+*vmid*
+:   A virtual machine identifier, which is a string that indicates the target
+    JVM. See [Virtual Machine Identifier].
+
+*interval*
+:   The sampling interval in the specified units, seconds (s) or milliseconds
+    (ms). Default units are milliseconds. This must be a positive integer. When
+    specified, the `jstat` command produces its output at each interval.
+
+*count*
+:   The number of samples to display. The default value is infinity, which
+    causes the `jstat` command to display statistics until the target JVM
+    terminates or the `jstat` command is terminated. This value must be a
+    positive integer.
+
+## Description
+
+The `jstat` command displays performance statistics for an instrumented Java
+HotSpot VM. The target JVM is identified by its virtual machine identifier, or
+`vmid` option.
+
+The `jstat` command supports two types of options, general options and output
+options. General options cause the `jstat` command to display simple usage and
+version information. Output options determine the content and format of the
+statistical output.
+
+All options and their functionality are subject to change or removal in future
+releases.
+
+## General Options
+
+If you specify one of the general options, then you can't specify any other
+option or parameter.
+
+`-help`
+:   Displays a help message.
+
+`-options`
+:   Displays a list of static options. See [Output Options for the jstat
+    Command].
+
+## Output Options for the jstat Command
+
+If you don't specify a general option, then you can specify output options.
+Output options determine the content and format of the `jstat` command's
+output, and consist of a single `statOption`, plus any of the other output
+options (`-h`, `-t`, and `-J`). The `statOption` must come first.
+
+Output is formatted as a table, with columns that are separated by spaces. A
+header row with titles describes the columns. Use the `-h` option to set the
+frequency at which the header is displayed. Column header names are consistent
+among the different options. In general, if two options provide a column with
+the same name, then the data source for the two columns is the same.
+
+Use the `-t` option to display a time-stamp column, labeled Timestamp as the
+first column of output. The Timestamp column contains the elapsed time, in
+seconds, since the target JVM started. The resolution of the time stamp is
+dependent on various factors and is subject to variation due to delayed thread
+scheduling on heavily loaded systems.
+
+Use the interval and count parameters to determine how frequently and how many
+times, respectively, the `jstat` command displays its output.
+
+**Note:**
+
+Don't write scripts to parse the `jstat` command's output because the format
+might change in future releases. If you write scripts that parse the `jstat`
+command output, then expect to modify them for future releases of this tool.
+
+`-statOption`
+:   Determines the statistics information that the `jstat` command displays.
+    The following lists the available options. Use the `-options` general
+    option to display the list of options for a particular platform
+    installation. See [Stat Options and Output].
+
+    `class`: Displays statistics about the behavior of the class loader.
+
+    `compiler`: Displays statistics about the behavior of the Java HotSpot VM
+    Just-in-Time compiler.
+
+    `gc`: Displays statistics about the behavior of the garbage collected heap.
+
+    `gccapacity`: Displays statistics about the capacities of the generations
+    and their corresponding spaces.
+
+    `gccause`: Displays a summary about garbage collection statistics (same as
+    `-gcutil`), with the cause of the last and current (when applicable)
+    garbage collection events.
+
+    `gcnew`: Displays statistics about the behavior of the new generation.
+
+    `gcnewcapacity`: Displays statistics about the sizes of the new generations
+    and their corresponding spaces.
+
+    `gcold`: Displays statistics about the behavior of the old generation and
+    metaspace statistics.
+
+    `gcoldcapacity`: Displays statistics about the sizes of the old generation.
+
+    `gcmetacapacity`: Displays statistics about the sizes of the metaspace.
+
+    `gcutil`: Displays a summary about garbage collection statistics.
+
+    `printcompilation`: Displays Java HotSpot VM compilation method statistics.
+
+`-J`*javaOption*
+:   Passes *javaOption* to the Java application launcher. For example,
+    `-J-Xms48m` sets the startup memory to 48 MB. For a complete list of
+    options, see [java](java.html).
+
+## Stat Options and Output
+
+The following information summarizes the columns that the `jstat` command
+outputs for each *statOption*.
+
+`-class` *option*
+:   Class loader statistics.
+
+    `Loaded`: Number of classes loaded.
+
+    `Bytes`: Number of KB loaded.
+
+    `Unloaded`: Number of classes unloaded.
+
+    `Bytes`: Number of KB unloaded.
+
+    `Time`: Time spent performing class loading and unloading operations.
+
+`-compiler` *option*
+:   Java HotSpot VM Just-in-Time compiler statistics.
+
+    `Compiled`: Number of compilation tasks performed.
+
+    `Failed`: Number of compilations tasks failed.
+
+    `Invalid`: Number of compilation tasks that were invalidated.
+
+    `Time`: Time spent performing compilation tasks.
+
+    `FailedType`: Compile type of the last failed compilation.
+
+    `FailedMethod`: Class name and method of the last failed compilation.
+
+`-gc` *option*
+:   Garbage collected heap statistics.
+
+    `S0C`: Current survivor space 0 capacity (KB).
+
+    `S1C`: Current survivor space 1 capacity (KB).
+
+    `S0U`: Survivor space 0 utilization (KB).
+
+    `S1U`: Survivor space 1 utilization (KB).
+
+    `EC`: Current eden space capacity (KB).
+
+    `EU`: Eden space utilization (KB).
+
+    `OC`: Current old space capacity (KB).
+
+    `OU`: Old space utilization (KB).
+
+    `MC`: Metaspace Committed Size (KB).
+
+    `MU`: Metaspace utilization (KB).
+
+    `CCSC`: Compressed class committed size (KB).
+
+    `CCSU`: Compressed class space used (KB).
+
+    `YGC`: Number of young generation garbage collection (GC) events.
+
+    `YGCT`: Young generation garbage collection time.
+
+    `FGC`: Number of full GC events.
+
+    `FGCT`: Full garbage collection time.
+
+    `GCT`: Total garbage collection time.
+
+`-gccapacity` *option*
+:   Memory pool generation and space capacities.
+
+    `NGCMN`: Minimum new generation capacity (KB).
+
+    `NGCMX`: Maximum new generation capacity (KB).
+
+    `NGC`: Current new generation capacity (KB).
+
+    `S0C`: Current survivor space 0 capacity (KB).
+
+    `S1C`: Current survivor space 1 capacity (KB).
+
+    `EC`: Current eden space capacity (KB).
+
+    `OGCMN`: Minimum old generation capacity (KB).
+
+    `OGCMX`: Maximum old generation capacity (KB).
+
+    `OGC`: Current old generation capacity (KB).
+
+    `OC`: Current old space capacity (KB).
+
+    `MCMN`: Minimum metaspace capacity (KB).
+
+    `MCMX`: Maximum metaspace capacity (KB).
+
+    `MC`: Metaspace Committed Size (KB).
+
+    `CCSMN`: Compressed class space minimum capacity (KB).
+
+    `CCSMX`: Compressed class space maximum capacity (KB).
+
+    `CCSC`: Compressed class committed size (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `FGC`: Number of full GC events.
+
+`-gccause` *option*
+:   This option displays the same summary of garbage collection statistics as
+    the `-gcutil` option, but includes the causes of the last garbage
+    collection event and (when applicable), the current garbage collection
+    event. In addition to the columns listed for `-gcutil`, this option adds
+    the following columns:
+
+    `LGCC`: Cause of last garbage collection
+
+    `GCC`: Cause of current garbage collection
+
+`-gcnew` *option*
+:   New generation statistics.
+
+    `S0C`: Current survivor space 0 capacity (KB).
+
+    `S1C`: Current survivor space 1 capacity (KB).
+
+    `S0U`: Survivor space 0 utilization (KB).
+
+    `S1U`: Survivor space 1 utilization (KB).
+
+    `TT`: Tenuring threshold.
+
+    `MTT`: Maximum tenuring threshold.
+
+    `DSS`: Desired survivor size (KB).
+
+    `EC`: Current eden space capacity (KB).
+
+    `EU`: Eden space utilization (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `YGCT`: Young generation garbage collection time.
+
+`-gcnewcapacity` *option*
+:   New generation space size statistics.
+
+    `NGCMN`: Minimum new generation capacity (KB).
+
+    `NGCMX`: Maximum new generation capacity (KB).
+
+    `NGC`: Current new generation capacity (KB).
+
+    `S0CMX`: Maximum survivor space 0 capacity (KB).
+
+    `S0C`: Current survivor space 0 capacity (KB).
+
+    `S1CMX`: Maximum survivor space 1 capacity (KB).
+
+    `S1C`: Current survivor space 1 capacity (KB).
+
+    `ECMX`: Maximum eden space capacity (KB).
+
+    `EC`: Current eden space capacity (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `FGC`: Number of full GC events.
+
+`-gcold` *option*
+:   Old generation size statistics.
+
+    `MC`: Metaspace Committed Size (KB).
+
+    `MU`: Metaspace utilization (KB).
+
+    `CCSC`: Compressed class committed size (KB).
+
+    `CCSU`: Compressed class space used (KB).
+
+    `OC`: Current old space capacity (KB).
+
+    `OU`: Old space utilization (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `FGC`: Number of full GC events.
+
+    `FGCT`: Full garbage collection time.
+
+    `GCT`: Total garbage collection time.
+
+`-gcoldcapacity` *option*
+:   Old generation statistics.
+
+    `OGCMN`: Minimum old generation capacity (KB).
+
+    `OGCMX`: Maximum old generation capacity (KB).
+
+    `OGC`: Current old generation capacity (KB).
+
+    `OC`: Current old space capacity (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `FGC`: Number of full GC events.
+
+    `FGCT`: Full garbage collection time.
+
+    `GCT`: Total garbage collection time.
+
+`-gcmetacapacity` *option*
+:   Metaspace size statistics.
+
+    `MCMN`: Minimum metaspace capacity (KB).
+
+    `MCMX`: Maximum metaspace capacity (KB).
+
+    `MC`: Metaspace Committed Size (KB).
+
+    `CCSMN`: Compressed class space minimum capacity (KB).
+
+    `CCSMX`: Compressed class space maximum capacity (KB).
+
+    `YGC`: Number of young generation GC events.
+
+    `FGC`: Number of full GC events.
+
+    `FGCT`: Full garbage collection time.
+
+    `GCT`: Total garbage collection time.
+
+`-gcutil` *option*
+:   Summary of garbage collection statistics.
+
+    `S0`: Survivor space 0 utilization as a percentage of the space's current
+    capacity.
+
+    `S1`: Survivor space 1 utilization as a percentage of the space's current
+    capacity.
+
+    `E`: Eden space utilization as a percentage of the space's current
+    capacity.
+
+    `O`: Old space utilization as a percentage of the space's current capacity.
+
+    `M`: Metaspace utilization as a percentage of the space's current capacity.
+
+    `CCS`: Compressed class space utilization as a percentage.
+
+    `YGC`: Number of young generation GC events.
+
+    `YGCT`: Young generation garbage collection time.
+
+    `FGC`: Number of full GC events.
+
+    `FGCT`: Full garbage collection time.
+
+    `GCT`: Total garbage collection time.
+
+`-printcompilation` *option*
+:   Java HotSpot VM compiler method statistics.
+
+    `Compiled`: Number of compilation tasks performed by the most recently
+    compiled method.
+
+    `Size`: Number of bytes of byte code of the most recently compiled method.
+
+    `Type`: Compilation type of the most recently compiled method.
+
+    `Method`: Class name and method name identifying the most recently compiled
+    method. Class name uses a slash (/) instead of a dot (.) as a name space
+    separator. The method name is the method within the specified class. The
+    format for these two fields is consistent with the HotSpot
+    `-XX:+PrintCompilation` option.
+
+## Virtual Machine Identifier
+
+The syntax of the `vmid` string corresponds to the syntax of a URI:
+
+>   \[*protocol*`:`\]\[`//`\]*lvmid*\[`@`*hostname*\[`:`*port*\]\[`/`*servername*\]
+
+The syntax of the `vmid` string corresponds to the syntax of a URI. The `vmid`
+string can vary from a simple integer that represents a local JVM to a more
+complex construction that specifies a communications protocol, port number, and
+other implementation-specific values.
+
+*protocol*
+:   The communications protocol. If the *protocol* value is omitted and a host
+    name isn't specified, then the default protocol is a platform-specific
+    optimized local protocol. If the *protocol* value is omitted and a host
+    name is specified, then the default protocol is `rmi`.
+
+*lvmid*
+:   The local virtual machine identifier for the target JVM. The *lvmid* is a
+    platform-specific value that uniquely identifies a JVM on a system. The
+    *lvmid* is the only required component of a virtual machine identifier. The
+    *lvmid* is typically, but not necessarily, the operating system's process
+    identifier for the target JVM process. You can use the `jps` command to
+    determine the *lvmid* provided the JVM processes is not running in a
+    separate docker instance. You can also determine the *lvmid* on Linux and
+    macOS platforms with the `ps` command, and on Windows with the Windows Task
+    Manager.
+
+*hostname*
+:   A host name or IP address that indicates the target host. If the *hostname*
+    value is omitted, then the target host is the local host.
+
+*port*
+:   The default port for communicating with the remote server. If the
+    *hostname* value is omitted or the *protocol* value specifies an optimized,
+    local protocol, then the *port* value is ignored. Otherwise, treatment of
+    the *port* parameter is implementation-specific. For the default `rmi`
+    protocol, the port value indicates the port number for the `rmiregistry` on
+    the remote host. If the *port* value is omitted and the *protocol* value
+    indicates `rmi`, then the default rmiregistry port (1099) is used.
+
+*servername*
+:   The treatment of the *servername* parameter depends on implementation. For
+    the optimized local protocol, this field is ignored. For the `rmi`
+    protocol, it represents the name of the RMI remote object on the remote
+    host.
+
+## Examples
+
+This section presents some examples of monitoring a local JVM with an *lvmid*
+of 21891.
+
+## The gcutil Option
+
+This example attaches to lvmid 21891 and takes 7 samples at 250 millisecond
+intervals and displays the output as specified by the `-gcutil` option.
+
+The output of this example shows that a young generation collection occurred
+between the third and fourth sample. The collection took 0.078 seconds and
+promoted objects from the eden space (E) to the old space (O), resulting in an
+increase of old space utilization from 66.80% to 68.19%. Before the collection,
+the survivor space was 97.02% utilized, but after this collection it's 91.03%
+utilized.
+
+```
+jstat -gcutil 21891 250 7
+  S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT     GCT
+  0.00  97.02  70.31  66.80  95.52  89.14      7    0.300     0    0.000    0.300
+  0.00  97.02  86.23  66.80  95.52  89.14      7    0.300     0    0.000    0.300
+  0.00  97.02  96.53  66.80  95.52  89.14      7    0.300     0    0.000    0.300
+ 91.03   0.00   1.98  68.19  95.89  91.24      8    0.378     0    0.000    0.378
+ 91.03   0.00  15.82  68.19  95.89  91.24      8    0.378     0    0.000    0.378
+ 91.03   0.00  17.80  68.19  95.89  91.24      8    0.378     0    0.000    0.378
+ 91.03   0.00  17.80  68.19  95.89  91.24      8    0.378     0    0.000    0.378
+```
+
+## Repeat the Column Header String
+
+This example attaches to lvmid 21891 and takes samples at 250 millisecond
+intervals and displays the output as specified by `-gcnew` option. In addition,
+it uses the `-h3` option to output the column header after every 3 lines of
+data.
+
+In addition to showing the repeating header string, this example shows that
+between the second and third samples, a young GC occurred. Its duration was
+0.001 seconds. The collection found enough active data that the survivor space
+0 utilization (S0U) would have exceeded the desired survivor size (DSS). As a
+result, objects were promoted to the old generation (not visible in this
+output), and the tenuring threshold (TT) was lowered from 31 to 2.
+
+Another collection occurs between the fifth and sixth samples. This collection
+found very few survivors and returned the tenuring threshold to 31.
+
+```
+jstat -gcnew -h3 21891 250
+ S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
+  64.0   64.0    0.0   31.7 31  31   32.0    512.0    178.6    249    0.203
+  64.0   64.0    0.0   31.7 31  31   32.0    512.0    355.5    249    0.203
+  64.0   64.0   35.4    0.0  2  31   32.0    512.0     21.9    250    0.204
+ S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
+  64.0   64.0   35.4    0.0  2  31   32.0    512.0    245.9    250    0.204
+  64.0   64.0   35.4    0.0  2  31   32.0    512.0    421.1    250    0.204
+  64.0   64.0    0.0   19.0 31  31   32.0    512.0     84.4    251    0.204
+ S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
+  64.0   64.0    0.0   19.0 31  31   32.0    512.0    306.7    251    0.204
+```
+
+## Include a Time Stamp for Each Sample
+
+This example attaches to lvmid 21891 and takes 3 samples at 250 millisecond
+intervals. The `-t` option is used to generate a time stamp for each sample in
+the first column.
+
+The Timestamp column reports the elapsed time in seconds since the start of the
+target JVM. In addition, the `-gcoldcapacity` output shows the old generation
+capacity (OGC) and the old space capacity (OC) increasing as the heap expands
+to meet allocation or promotion demands. The old generation capacity (OGC) has
+grown from 11,696 KB to 13,820 KB after the eighty-first full garbage
+collection (FGC). The maximum capacity of the generation (and space) is 60,544
+KB (OGCMX), so it still has room to expand.
+
+```
+Timestamp      OGCMN    OGCMX     OGC       OC       YGC   FGC    FGCT    GCT
+          150.1   1408.0  60544.0  11696.0  11696.0   194    80    2.874   3.799
+          150.4   1408.0  60544.0  13820.0  13820.0   194    81    2.938   3.863
+          150.7   1408.0  60544.0  13820.0  13820.0   194    81    2.938   3.863
+```
+
+## Monitor Instrumentation for a Remote JVM
+
+This example attaches to lvmid 40496 on the system named `remote.domain` using
+the `-gcutil` option, with samples taken every second indefinitely.
+
+The lvmid is combined with the name of the remote host to construct a vmid of
+`40496@remote.domain`. This vmid results in the use of the `rmi` protocol to
+communicate to the default `jstatd` server on the remote host. The `jstatd`
+server is located using the `rmiregistry` command on `remote.domain` that's
+bound to the default port of the `rmiregistry` command (port 1099).
+
+```
+jstat -gcutil 40496@remote.domain 1000
+... output omitted
+```
diff --git a/src/jdk.jconsole/share/man/jconsole.1 b/src/jdk.jconsole/share/man/jconsole.1
deleted file mode 100644
index ec70040acf4..00000000000
--- a/src/jdk.jconsole/share/man/jconsole.1
+++ /dev/null
@@ -1,104 +0,0 @@
-.\" Copyright (c) 2004, 2018, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JCONSOLE" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jconsole - start a graphical console to monitor and manage Java
-applications
-.SH SYNOPSIS
-.PP
-\f[V]jconsole\f[R] [\f[V]-interval=\f[R]\f[I]n\f[R]] [\f[V]-notile\f[R]]
-[\f[V]-plugin\f[R] \f[I]path\f[R]] [\f[V]-version\f[R]]
-[\f[I]connection\f[R] ...
-] [\f[V]-J\f[R]\f[I]input_arguments\f[R]]
-.PP
-\f[V]jconsole\f[R] \f[V]-help\f[R]
-.SH OPTIONS
-.TP
-\f[V]-interval\f[R]
-Sets the update interval to \f[V]n\f[R] seconds (default is 4 seconds).
-.TP
-\f[V]-notile\f[R]
-Doesn\[aq]t tile the windows for two or more connections.
-.TP
-\f[V]-pluginpath\f[R] \f[I]path\f[R]
-Specifies the path that \f[V]jconsole\f[R] uses to look up plug-ins.
-The plug-in \f[I]path\f[R] should contain a provider-configuration file
-named \f[V]META-INF/services/com.sun.tools.jconsole.JConsolePlugin\f[R]
-that contains one line for each plug-in.
-The line specifies the fully qualified class name of the class
-implementing the \f[V]com.sun.tools.jconsole.JConsolePlugin\f[R] class.
-.TP
-\f[V]-version\f[R]
-Prints the program version.
-.TP
-\f[I]connection\f[R] = \f[I]pid\f[R] | \f[I]host\f[R]\f[V]:\f[R]\f[I]port\f[R] | \f[I]jmxURL\f[R]
-A connection is described by either \f[I]pid\f[R],
-\f[I]host\f[R]\f[V]:\f[R]\f[I]port\f[R] or \f[I]jmxURL\f[R].
-.RS
-.IP \[bu] 2
-The \f[I]pid\f[R] value is the process ID of a target process.
-The JVM must be running with the same user ID as the user ID running the
-\f[V]jconsole\f[R] command.
-.IP \[bu] 2
-The \f[I]host\f[R]\f[V]:\f[R]\f[I]port\f[R] values are the name of the
-host system on which the JVM is running, and the port number specified
-by the system property \f[V]com.sun.management.jmxremote.port\f[R] when
-the JVM was started.
-.IP \[bu] 2
-The \f[I]jmxUrl\f[R] value is the address of the JMX agent to be
-connected to as described in JMXServiceURL.
-.RE
-.TP
-\f[V]-J\f[R]\f[I]input_arguments\f[R]
-Passes \f[I]input_arguments\f[R] to the JVM on which the
-\f[V]jconsole\f[R] command is run.
-.TP
-\f[V]-help\f[R] or \f[V]--help\f[R]
-Displays the help message for the command.
-.SH DESCRIPTION
-.PP
-The \f[V]jconsole\f[R] command starts a graphical console tool that lets
-you monitor and manage Java applications and virtual machines on a local
-or remote machine.
-.PP
-On Windows, the \f[V]jconsole\f[R] command doesn\[aq]t associate with a
-console window.
-It does, however, display a dialog box with error information when the
-\f[V]jconsole\f[R] command fails.
diff --git a/src/jdk.jconsole/share/man/jconsole.md b/src/jdk.jconsole/share/man/jconsole.md
new file mode 100644
index 00000000000..59c84a0431a
--- /dev/null
+++ b/src/jdk.jconsole/share/man/jconsole.md
@@ -0,0 +1,86 @@
+---
+# Copyright (c) 2004, 2018, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JCONSOLE(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jconsole - start a graphical console to monitor and manage Java applications
+
+## Synopsis
+
+`jconsole` \[`-interval=`*n*\] \[`-notile`\] \[`-plugin` *path*\]
+\[`-version`\] \[*connection* ... \] \[`-J`*input\_arguments*\]
+
+`jconsole` `-help`
+
+## Options
+
+`-interval`
+:   Sets the update interval to `n` seconds (default is 4 seconds).
+
+`-notile`
+:   Doesn't tile the windows for two or more connections.
+
+`-pluginpath` *path*
+:   Specifies the path that `jconsole` uses to look up plug-ins. The plug-in
+    *path* should contain a provider-configuration file named
+    `META-INF/services/com.sun.tools.jconsole.JConsolePlugin` that contains one
+    line for each plug-in. The line specifies the fully qualified class name of
+    the class implementing the `com.sun.tools.jconsole.JConsolePlugin` class.
+
+`-version`
+:   Prints the program version.
+
+*connection* = *pid* \| *host*`:`*port* \| *jmxURL*
+:   A connection is described by either *pid*, *host*`:`*port* or *jmxURL*.
+
+    -   The *pid* value is the process ID of a target process. The JVM must be
+        running with the same user ID as the user ID running the `jconsole`
+        command.
+
+    -   The *host*`:`*port* values are the name of the host system on which the
+        JVM is running, and the port number specified by the system property
+        `com.sun.management.jmxremote.port` when the JVM was started.
+
+    -   The *jmxUrl* value is the address of the JMX agent to be connected to
+        as described in JMXServiceURL.
+
+`-J`*input\_arguments*
+:   Passes *input\_arguments* to the JVM on which the `jconsole` command is
+    run.
+
+`-help` or `--help`
+:   Displays the help message for the command.
+
+## Description
+
+The `jconsole` command starts a graphical console tool that lets you monitor
+and manage Java applications and virtual machines on a local or remote machine.
+
+On Windows, the `jconsole` command doesn't associate with a console window. It
+does, however, display a dialog box with error information when the `jconsole`
+command fails.
diff --git a/src/jdk.jdeps/share/man/javap.1 b/src/jdk.jdeps/share/man/javap.1
deleted file mode 100644
index 27b0a29d0ba..00000000000
--- a/src/jdk.jdeps/share/man/javap.1
+++ /dev/null
@@ -1,259 +0,0 @@
-.\" Copyright (c) 1994, 2020, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JAVAP" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-javap - disassemble one or more class files
-.SH SYNOPSIS
-.PP
-\f[V]javap\f[R] [\f[I]options\f[R]] \f[I]classes\f[R]...
-.TP
-\f[I]options\f[R]
-Specifies the command-line options.
-See \f[B]Options for javap\f[R].
-.TP
-\f[I]classes\f[R]
-Specifies one or more classes separated by spaces to be processed for
-annotations.
-You can specify a class that can be found in the class path by its file
-name, URL, or by its fully qualified class name.
-.RS
-.PP
-Examples:
-.RS
-.PP
-\f[V]path/to/MyClass.class\f[R]
-.RE
-.RS
-.PP
-\f[V]jar:file:///path/to/MyJar.jar!/mypkg/MyClass.class\f[R]
-.RE
-.RS
-.PP
-\f[V]java.lang.Object\f[R]
-.RE
-.RE
-.SH DESCRIPTION
-.PP
-The \f[V]javap\f[R] command disassembles one or more class files.
-The output depends on the options used.
-When no options are used, the \f[V]javap\f[R] command prints the
-protected and public fields, and methods of the classes passed to it.
-.PP
-The \f[V]javap\f[R] command isn\[aq]t multirelease JAR aware.
-Using the class path form of the command results in viewing the base
-entry in all JAR files, multirelease or not.
-Using the URL form, you can use the URL form of an argument to specify a
-specific version of a class to be disassembled.
-.PP
-The \f[V]javap\f[R] command prints its output to \f[V]stdout\f[R].
-.PP
-\f[B]Note:\f[R]
-.PP
-In tools that support \f[V]--\f[R] style options, the GNU-style options
-can use the equal sign (\f[V]=\f[R]) instead of a white space to
-separate the name of an option from its value.
-.SH OPTIONS FOR JAVAP
-.TP
-\f[V]--help\f[R], \f[V]-help\f[R] , \f[V]-h\f[R], or \f[V]-?\f[R]
-Prints a help message for the \f[V]javap\f[R] command.
-.TP
-\f[V]-version\f[R]
-Prints release information.
-.TP
-\f[V]-verbose\f[R] or \f[V]-v\f[R]
-Prints additional information about the selected class.
-.TP
-\f[V]-l\f[R]
-Prints line and local variable tables.
-.TP
-\f[V]-public\f[R]
-Shows only public classes and members.
-.TP
-\f[V]-protected\f[R]
-Shows only protected and public classes and members.
-.TP
-\f[V]-package\f[R]
-Shows package/protected/public classes and members (default).
-.TP
-\f[V]-private\f[R] or \f[V]-p\f[R]
-Shows all classes and members.
-.TP
-\f[V]-c\f[R]
-Prints disassembled code, for example, the instructions that comprise
-the Java bytecodes, for each of the methods in the class.
-.TP
-\f[V]-s\f[R]
-Prints internal type signatures.
-.TP
-\f[V]-sysinfo\f[R]
-Shows system information (path, size, date, SHA-256 hash) of the class
-being processed.
-.TP
-\f[V]-verify\f[R]
-Prints additional class verification info.
-.TP
-\f[V]-constants\f[R]
-Shows \f[V]static final\f[R] constants.
-.TP
-\f[V]--module\f[R] \f[I]module\f[R] or \f[V]-m\f[R] \f[I]module\f[R]
-Specifies the module containing classes to be disassembled.
-.TP
-\f[V]--module-path\f[R] \f[I]path\f[R]
-Specifies where to find application modules.
-.TP
-\f[V]--system\f[R] \f[I]jdk\f[R]
-Specifies where to find system modules.
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R], \f[V]-classpath\f[R] \f[I]path\f[R], or \f[V]-cp\f[R] \f[I]path\f[R]
-Specifies the path that the \f[V]javap\f[R] command uses to find user
-class files.
-It overrides the default or the \f[V]CLASSPATH\f[R] environment variable
-when it\[aq]s set.
-.TP
-\f[V]-bootclasspath\f[R] \f[I]path\f[R]
-Overrides the location of bootstrap class files.
-.TP
-\f[V]--multi-release\f[R] \f[I]version\f[R]
-Specifies the version to select in multi-release JAR files.
-.TP
-\f[V]-J\f[R]\f[I]option\f[R]
-Passes the specified option to the JVM.
-For example:
-.RS
-.IP
-.nf
-\f[CB]
-javap -J-version
-
-javap -J-Djava.security.manager -J-Djava.security.policy=MyPolicy MyClassName
-\f[R]
-.fi
-.PP
-See \f[I]Overview of Java Options\f[R] in \f[B]java\f[R].
-.RE
-.SH JAVAP EXAMPLE
-.PP
-Compile the following \f[V]HelloWorldFrame\f[R] class:
-.IP
-.nf
-\f[CB]
-import java.awt.Graphics;
-
-import javax.swing.JFrame;
-import javax.swing.JPanel;
-
-public class HelloWorldFrame extends JFrame {
-
-   String message = \[dq]Hello World!\[dq];
-
-   public HelloWorldFrame(){
-        setContentPane(new JPanel(){
-            \[at]Override
-            protected void paintComponent(Graphics g) {
-                g.drawString(message, 15, 30);
-            }
-        });
-        setSize(100, 100);
-    }
-    public static void main(String[] args) {
-        HelloWorldFrame frame = new HelloWorldFrame();
-        frame.setVisible(true);
-
-    }
-
-}
-\f[R]
-.fi
-.PP
-The output from the \f[V]javap HelloWorldFrame.class\f[R] command yields
-the following:
-.IP
-.nf
-\f[CB]
-Compiled from \[dq]HelloWorldFrame.java\[dq]
-public class HelloWorldFrame extends javax.swing.JFrame {
-  java.lang.String message;
-  public HelloWorldFrame();
-  public static void main(java.lang.String[]);
-}
-\f[R]
-.fi
-.PP
-The output from the \f[V]javap -c HelloWorldFrame.class\f[R] command
-yields the following:
-.IP
-.nf
-\f[CB]
-Compiled from \[dq]HelloWorldFrame.java\[dq]
-public class HelloWorldFrame extends javax.swing.JFrame {
-  java.lang.String message;
-
-  public HelloWorldFrame();
-    Code:
-       0: aload_0
-       1: invokespecial #1        // Method javax/swing/JFrame.\[dq]<init>\[dq]:()V
-       4: aload_0
-       5: ldc           #2        // String Hello World!
-       7: putfield      #3        // Field message:Ljava/lang/String;
-      10: aload_0
-      11: new           #4        // class HelloWorldFrame$1
-      14: dup
-      15: aload_0
-      16: invokespecial #5        // Method HelloWorldFrame$1.\[dq]<init>\[dq]:(LHelloWorldFrame;)V
-      19: invokevirtual #6        // Method setContentPane:(Ljava/awt/Container;)V
-      22: aload_0
-      23: bipush        100
-      25: bipush        100
-      27: invokevirtual #7        // Method setSize:(II)V
-      30: return
-
-  public static void main(java.lang.String[]);
-    Code:
-       0: new           #8        // class HelloWorldFrame
-       3: dup
-       4: invokespecial #9        // Method \[dq]<init>\[dq]:()V
-       7: astore_1
-       8: aload_1
-       9: iconst_1
-      10: invokevirtual #10       // Method setVisible:(Z)V
-      13: return
-}
-\f[R]
-.fi
diff --git a/src/jdk.jdeps/share/man/javap.md b/src/jdk.jdeps/share/man/javap.md
new file mode 100644
index 00000000000..814db56b3ba
--- /dev/null
+++ b/src/jdk.jdeps/share/man/javap.md
@@ -0,0 +1,227 @@
+---
+# Copyright (c) 1994, 2020, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JAVAP(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+javap - disassemble one or more class files
+
+## Synopsis
+
+`javap` \[*options*\] *classes*...
+
+*options*
+:   Specifies the command-line options. See [Options for javap].
+
+*classes*
+:   Specifies one or more classes separated by spaces to be processed for
+    annotations. You can specify a class that can be found in the class path by
+    its file name, URL, or by its fully qualified class name.
+
+    Examples:
+
+    >   `path/to/MyClass.class`
+
+    >   `jar:file:///path/to/MyJar.jar!/mypkg/MyClass.class`
+
+    >   `java.lang.Object`
+
+## Description
+
+The `javap` command disassembles one or more class files. The output depends on
+the options used. When no options are used, the `javap` command prints the
+protected and public fields, and methods of the classes passed to it.
+
+The `javap` command isn't multirelease JAR aware. Using the class path form of
+the command results in viewing the base entry in all JAR files, multirelease or
+not. Using the URL form, you can use the URL form of an argument to specify a
+specific version of a class to be disassembled.
+
+The `javap` command prints its output to `stdout`.
+
+**Note:**
+
+In tools that support `--` style options, the GNU-style options can use the
+equal sign (`=`) instead of a white space to separate the name of an option
+from its value.
+
+## Options for javap
+
+`--help`, `-help` , `-h`, or `-?`
+:   Prints a help message for the `javap` command.
+
+`-version`
+:   Prints release information.
+
+`-verbose` or `-v`
+:   Prints additional information about the selected class.
+
+`-l`
+:   Prints line and local variable tables.
+
+`-public`
+:   Shows only public classes and members.
+
+`-protected`
+:   Shows only protected and public classes and members.
+
+`-package`
+:   Shows package/protected/public classes and members (default).
+
+`-private` or `-p`
+:   Shows all classes and members.
+
+`-c`
+:   Prints disassembled code, for example, the instructions that comprise the
+    Java bytecodes, for each of the methods in the class.
+
+`-s`
+:   Prints internal type signatures.
+
+`-sysinfo`
+:   Shows system information (path, size, date, SHA-256 hash) of the class being
+    processed.
+
+`-verify`
+:   Prints additional class verification info.
+
+`-constants`
+:   Shows `static final` constants.
+
+`--module` *module* or `-m` *module*
+:   Specifies the module containing classes to be disassembled.
+
+`--module-path` *path*
+:   Specifies where to find application modules.
+
+`--system` *jdk*
+:   Specifies where to find system modules.
+
+`--class-path` *path*, `-classpath` *path*, or `-cp` *path*
+:   Specifies the path that the `javap` command uses to find user class files.
+    It overrides the default or the `CLASSPATH` environment variable when it's
+    set.
+
+`-bootclasspath` *path*
+:   Overrides the location of bootstrap class files.
+
+`--multi-release` *version*
+:   Specifies the version to select in multi-release JAR files.
+
+`-J`*option*
+:   Passes the specified option to the JVM. For example:
+
+    ```
+    javap -J-version
+
+    javap -J-Djava.security.manager -J-Djava.security.policy=MyPolicy MyClassName
+    ```
+
+    See *Overview of Java Options* in [java](java.html).
+
+## javap Example
+
+Compile the following `HelloWorldFrame` class:
+
+```
+import java.awt.Graphics;
+
+import javax.swing.JFrame;
+import javax.swing.JPanel;
+
+public class HelloWorldFrame extends JFrame {
+
+   String message = "Hello World!";
+
+   public HelloWorldFrame(){
+        setContentPane(new JPanel(){
+            @Override
+            protected void paintComponent(Graphics g) {
+                g.drawString(message, 15, 30);
+            }
+        });
+        setSize(100, 100);
+    }
+    public static void main(String[] args) {
+        HelloWorldFrame frame = new HelloWorldFrame();
+        frame.setVisible(true);
+
+    }
+
+}
+```
+
+The output from the `javap HelloWorldFrame.class` command yields the following:
+
+```
+Compiled from "HelloWorldFrame.java"
+public class HelloWorldFrame extends javax.swing.JFrame {
+  java.lang.String message;
+  public HelloWorldFrame();
+  public static void main(java.lang.String[]);
+}
+```
+
+The output from the `javap -c HelloWorldFrame.class` command yields the
+following:
+
+```
+Compiled from "HelloWorldFrame.java"
+public class HelloWorldFrame extends javax.swing.JFrame {
+  java.lang.String message;
+
+  public HelloWorldFrame();
+    Code:
+       0: aload_0
+       1: invokespecial #1        // Method javax/swing/JFrame."<init>":()V
+       4: aload_0
+       5: ldc           #2        // String Hello World!
+       7: putfield      #3        // Field message:Ljava/lang/String;
+      10: aload_0
+      11: new           #4        // class HelloWorldFrame$1
+      14: dup
+      15: aload_0
+      16: invokespecial #5        // Method HelloWorldFrame$1."<init>":(LHelloWorldFrame;)V
+      19: invokevirtual #6        // Method setContentPane:(Ljava/awt/Container;)V
+      22: aload_0
+      23: bipush        100
+      25: bipush        100
+      27: invokevirtual #7        // Method setSize:(II)V
+      30: return
+
+  public static void main(java.lang.String[]);
+    Code:
+       0: new           #8        // class HelloWorldFrame
+       3: dup
+       4: invokespecial #9        // Method "<init>":()V
+       7: astore_1
+       8: aload_1
+       9: iconst_1
+      10: invokevirtual #10       // Method setVisible:(Z)V
+      13: return
+}
+```
diff --git a/src/jdk.jdeps/share/man/jdeprscan.1 b/src/jdk.jdeps/share/man/jdeprscan.1
deleted file mode 100644
index fc13f05c449..00000000000
--- a/src/jdk.jdeps/share/man/jdeprscan.1
+++ /dev/null
@@ -1,271 +0,0 @@
-.\" Copyright (c) 2017, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JDEPRSCAN" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jdeprscan - static analysis tool that scans a jar file (or some other
-aggregation of class files) for uses of deprecated API elements
-.SH SYNOPSIS
-.PP
-\f[V]jdeprscan\f[R] [\f[I]options\f[R]]
-{\f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R]}
-.TP
-\f[I]options\f[R]
-See \f[B]Options for the jdeprscan Command\f[R]
-.TP
-\f[I]dir\f[R]|\f[I]jar\f[R]|\f[I]class\f[R]
-\f[V]jdeprscan\f[R] command scans each argument for usages of deprecated
-APIs.
-The arguments can be a:
-.RS
-.IP \[bu] 2
-\f[I]dir\f[R]: Directory
-.IP \[bu] 2
-\f[I]jar\f[R]: JAR file
-.IP \[bu] 2
-\f[I]class\f[R]: Class name or class file
-.PP
-The class name should use a dot (\f[V].\f[R]) as a separator.
-For example:
-.PP
-\f[V]java.lang.Thread\f[R]
-.PP
-For nested classes, the dollar sign \f[V]$\f[R] separator character
-should be used.
-For example:
-.PP
-\f[V]java.lang.Thread$State\f[R]
-.PP
-A class file can also be named.
-For example:
-.PP
-\f[V]build/classes/java/lang/Thread$State.class\f[R]
-.RE
-.SH DESCRIPTION
-.PP
-The \f[V]jdeprscan\f[R] tool is a static analysis tool provided by the
-JDK that scans a JAR file or some other aggregation of class files for
-uses of deprecated API elements.
-The deprecated APIs identified by the \f[V]jdeprscan\f[R] tool are only
-those that are defined by Java SE.
-Deprecated APIs defined by third-party libraries aren\[aq]t reported.
-.PP
-To scan a JAR file or a set of class files, you must first ensure that
-all of the classes that the scanned classes depend upon are present in
-the class path.
-Set the class path using the \f[V]--class-path\f[R] option described in
-\f[B]Options for the jdeprscan Command\f[R].
-Typically, you would use the same class path as the one that you use
-when invoking your application.
-.PP
-If the \f[V]jdeprscan\f[R] can\[aq]t find all the dependent classes, it
-will generate an error message for each class that\[aq]s missing.
-These error messages are typically of the form:
-.RS
-.PP
-\f[V]error: cannot find class ...\f[R]
-.RE
-.PP
-If these errors occur, then you must adjust the class path so that it
-includes all dependent classes.
-.SH OPTIONS FOR THE JDEPRSCAN COMMAND
-.PP
-The following options are available:
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Provides a search path for resolution of dependent classes.
-.RS
-.PP
-\f[I]path\f[R] can be a search path that consists of one or more
-directories separated by the system-specific path separator.
-For example:
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]--class-path /some/directory:/another/different/dir\f[R]
-.RE
-.RE
-.PP
-\f[B]Note:\f[R]
-.PP
-On Windows, use a semicolon (\f[V];\f[R]) as the separator instead of a
-colon (\f[V]:\f[R]).
-.IP \[bu] 2
-\f[B]Windows:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]--class-path \[rs]some\[rs]directory;\[rs]another\[rs]different\[rs]dir\f[R]
-.RE
-.RE
-.RE
-.TP
-\f[V]--for-removal\f[R]
-Limits scanning or listing to APIs that are deprecated for removal.
-Can\[aq]t be used with a release value of 6, 7, or 8.
-.TP
-\f[V]--full-version\f[R]
-Prints out the full version string of the tool.
-.TP
-\f[V]--help\f[R] or \f[V]-h\f[R]
-Prints out a full help message.
-.TP
-\f[V]--list\f[R] or \f[V]-l\f[R]
-Prints the set of deprecated APIs.
-No scanning is done, so no directory, jar, or class arguments should be
-provided.
-.TP
-\f[V]--release\f[R] \f[V]6\f[R]|\f[V]7\f[R]|\f[V]8\f[R]|\f[V]9\f[R]
-Specifies the Java SE release that provides the set of deprecated APIs
-for scanning.
-.TP
-\f[V]--verbose\f[R] or \f[V]-v\f[R]
-Enables additional message output during processing.
-.TP
-\f[V]--version\f[R]
-Prints out the abbreviated version string of the tool.
-.SH EXAMPLE OF JDEPRSCAN OUTPUT
-.PP
-The JAR file for this library will be named something similar to
-\f[V]commons-math3-3.6.1.jar\f[R].
-To scan this JAR file for the use of deprecated APIs, run the following
-command:
-.RS
-.PP
-\f[V]jdeprscan commons-math3-3.6.1.jar\f[R]
-.RE
-.PP
-This command produces several lines of output.
-For example, one line of output might be:
-.IP
-.nf
-\f[CB]
-class org/apache/commons/math3/util/MathUtils uses deprecated method java/lang/Double::<init>(D)V
-\f[R]
-.fi
-.PP
-\f[B]Note:\f[R]
-.PP
-The class name is specified using the slash-separated binary name as
-described in JVMS 4.2.1.
-This is the form used internally in class files.
-.PP
-The deprecated API it uses is a method on the \f[V]java.lang.Double\f[R]
-class.
-.PP
-The name of the deprecated method is \f[V]<init>\f[R], which is a
-special name that means that the method is actually a constructor.
-Another special name is \f[V]<clinit>\f[R], which indicates a class
-static initializer.
-.PP
-Other methods are listed just by their method name.
-Following the method name is the argument list and return type:
-.RS
-.PP
-\f[V](D)V\f[R]
-.RE
-.PP
-This indicates that it takes just one double value (a primitive) and
-returns void.
-The argument and return types can become cryptic.
-For example, another line of output might be:
-.IP
-.nf
-\f[CB]
-class org/apache/commons/math3/util/Precision uses deprecated method java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal;
-\f[R]
-.fi
-.PP
-In this line of output, the deprecated method is on class
-\f[V]java.math.BigDecimal\f[R], and the method is \f[V]setScale()\f[R].
-In this case, the \f[V](II)\f[R] means that it takes two \f[V]int\f[R]
-arguments.
-The \f[V]Ljava/math/BigDecimal;\f[R] after the parentheses means that it
-returns a reference to \f[V]java.math.BigDecimal\f[R].
-.SH JDEPRSCAN ANALYSIS CAN BE VERSION-SPECIFIC
-.PP
-You can use \f[V]jdeprscan\f[R] relative to the previous three JDK
-releases.
-For example, if you are running JDK 9, then you can check against JDK 8,
-7, and 6.
-.PP
-As an example, look at this code snippet:
-.IP
-.nf
-\f[CB]
-public class Deprecations {
-   SecurityManager sm = new RMISecurityManager();    // deprecated in 8
-   Boolean b2 = new Boolean(true);          // deprecated in 9
-}
-\f[R]
-.fi
-.PP
-The complete class compiles without warnings in JDK 7.
-.PP
-If you run \f[V]jdeprscan\f[R] on a system with JDK 9, then you see:
-.IP
-.nf
-\f[CB]
-$ jdeprscan --class-path classes --release 7 example.Deprecations
-(no output)
-\f[R]
-.fi
-.PP
-Run \f[V]jdeprscan\f[R] with a release value of 8:
-.IP
-.nf
-\f[CB]
-$ jdeprscan --class-path classes --release 8 example.Deprecations
-class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
-class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
-\f[R]
-.fi
-.PP
-Run \f[V]jdeprscan\f[R] on JDK 9:
-.IP
-.nf
-\f[CB]
-$ jdeprscan --class-path classes example.Deprecations
-class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
-class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
-class example/Deprecations uses method java/lang/Boolean <init> (Z)V deprecated
-\f[R]
-.fi
diff --git a/src/jdk.jdeps/share/man/jdeprscan.md b/src/jdk.jdeps/share/man/jdeprscan.md
new file mode 100644
index 00000000000..8f76b29aee3
--- /dev/null
+++ b/src/jdk.jdeps/share/man/jdeprscan.md
@@ -0,0 +1,217 @@
+---
+# Copyright (c) 2017, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JDEPRSCAN(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jdeprscan - static analysis tool that scans a jar file (or some other
+aggregation of class files) for uses of deprecated API elements
+
+## Synopsis
+
+`jdeprscan` \[*options*\] {*dir*\|*jar*\|*class*}
+
+*options*
+:   See [Options for the jdeprscan Command]
+
+*dir*\|*jar*\|*class*
+:   `jdeprscan` command scans each argument for usages of deprecated APIs. The
+    arguments can be a:
+
+    -   *dir*: Directory
+
+    -   *jar*: JAR file
+
+    -   *class*: Class name or class file
+
+    The class name should use a dot (`.`) as a separator. For example:
+
+    `java.lang.Thread`
+
+    For nested classes, the dollar sign `$` separator character should be used.
+    For example:
+
+    `java.lang.Thread$State`
+
+    A class file can also be named. For example:
+
+    `build/classes/java/lang/Thread$State.class`
+
+## Description
+
+The `jdeprscan` tool is a static analysis tool provided by the JDK that scans a
+JAR file or some other aggregation of class files for uses of deprecated API
+elements. The deprecated APIs identified by the `jdeprscan` tool are only those
+that are defined by Java SE. Deprecated APIs defined by third-party libraries
+aren't reported.
+
+To scan a JAR file or a set of class files, you must first ensure that all of
+the classes that the scanned classes depend upon are present in the class
+path. Set the class path using the `--class-path` option described in [Options
+for the jdeprscan Command]. Typically, you would use the same class path as
+the one that you use when invoking your application.
+
+If the `jdeprscan` can't find all the dependent classes, it will generate an
+error message for each class that's missing. These error messages are typically
+of the form:
+
+>   `error: cannot find class ...`
+
+If these errors occur, then you must adjust the class path so that it includes
+all dependent classes.
+
+## Options for the jdeprscan Command
+
+The following options are available:
+
+`--class-path` *path*
+:   Provides a search path for resolution of dependent classes.
+
+    *path* can be a search path that consists of one or more directories
+    separated by the system-specific path separator. For example:
+
+    -   **Linux and macOS:**
+
+        >   `--class-path /some/directory:/another/different/dir`
+
+    **Note:**
+
+    On Windows, use a semicolon (`;`) as the separator instead of a colon
+    (`:`).
+
+    -   **Windows:**
+
+        >   `--class-path \some\directory;\another\different\dir`
+
+`--for-removal`
+:   Limits scanning or listing to APIs that are deprecated for removal. Can't
+    be used with a release value of 6, 7, or 8.
+
+`--full-version`
+:   Prints out the full version string of the tool.
+
+`--help` or `-h`
+:   Prints out a full help message.
+
+`--list` or `-l`
+:   Prints the set of deprecated APIs. No scanning is done, so no directory,
+    jar, or class arguments should be provided.
+
+`--release` `6`\|`7`\|`8`\|`9`
+:   Specifies the Java SE release that provides the set of deprecated APIs for
+    scanning.
+
+`--verbose` or `-v`
+:   Enables additional message output during processing.
+
+`--version`
+:   Prints out the abbreviated version string of the tool.
+
+## Example of jdeprscan Output
+
+The JAR file for this library will be named something similar to
+`commons-math3-3.6.1.jar`. To scan this JAR file for the use of deprecated
+APIs, run the following command:
+
+>   `jdeprscan commons-math3-3.6.1.jar`
+
+This command produces several lines of output. For example, one line of output
+might be:
+
+```
+class org/apache/commons/math3/util/MathUtils uses deprecated method java/lang/Double::<init>(D)V
+```
+
+**Note:**
+
+The class name is specified using the slash-separated binary name as described
+in JVMS 4.2.1. This is the form used internally in class files.
+
+The deprecated API it uses is a method on the `java.lang.Double` class.
+
+The name of the deprecated method is `<init>`, which is a special name that
+means that the method is actually a constructor. Another special name is
+`<clinit>`, which indicates a class static initializer.
+
+Other methods are listed just by their method name. Following the method name
+is the argument list and return type:
+
+>   `(D)V`
+
+This indicates that it takes just one double value (a primitive) and returns
+void. The argument and return types can become cryptic. For example, another
+line of output might be:
+
+```
+class org/apache/commons/math3/util/Precision uses deprecated method java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal;
+```
+
+In this line of output, the deprecated method is on class
+`java.math.BigDecimal`, and the method is `setScale()`. In this case, the
+`(II)` means that it takes two `int` arguments. The `Ljava/math/BigDecimal;`
+after the parentheses means that it returns a reference to
+`java.math.BigDecimal`.
+
+## jdeprscan Analysis Can Be Version-Specific
+
+You can use `jdeprscan` relative to the previous three JDK releases. For
+example, if you are running JDK 9, then you can check against JDK 8, 7, and 6.
+
+As an example, look at this code snippet:
+
+```
+public class Deprecations {
+   SecurityManager sm = new RMISecurityManager();    // deprecated in 8
+   Boolean b2 = new Boolean(true);          // deprecated in 9
+}
+```
+
+The complete class compiles without warnings in JDK 7.
+
+If you run `jdeprscan` on a system with JDK 9, then you see:
+
+```
+$ jdeprscan --class-path classes --release 7 example.Deprecations
+(no output)
+```
+
+Run `jdeprscan` with a release value of 8:
+
+```
+$ jdeprscan --class-path classes --release 8 example.Deprecations
+class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
+class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
+```
+
+Run `jdeprscan` on JDK 9:
+
+```
+$ jdeprscan --class-path classes example.Deprecations
+class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
+class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
+class example/Deprecations uses method java/lang/Boolean <init> (Z)V deprecated
+```
diff --git a/src/jdk.jdeps/share/man/jdeps.1 b/src/jdk.jdeps/share/man/jdeps.1
deleted file mode 100644
index d3dde37e3b9..00000000000
--- a/src/jdk.jdeps/share/man/jdeps.1
+++ /dev/null
@@ -1,338 +0,0 @@
-.\" Copyright (c) 2013, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JDEPS" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jdeps - launch the Java class dependency analyzer
-.SH SYNOPSIS
-.PP
-\f[V]jdeps\f[R] [\f[I]options\f[R]] \f[I]path\f[R] ...
-.TP
-\f[I]options\f[R]
-Command-line options.
-For detailed descriptions of the options that can be used, see
-.RS
-.IP \[bu] 2
-\f[B]Possible Options\f[R]
-.IP \[bu] 2
-\f[B]Module Dependence Analysis Options\f[R]
-.IP \[bu] 2
-\f[B]Options to Filter Dependences\f[R]
-.IP \[bu] 2
-\f[B]Options to Filter Classes to be Analyzed\f[R]
-.RE
-.TP
-\f[I]path\f[R]
-A pathname to the \f[V].class\f[R] file, directory, or JAR file to
-analyze.
-.SH DESCRIPTION
-.PP
-The \f[V]jdeps\f[R] command shows the package-level or class-level
-dependencies of Java class files.
-The input class can be a path name to a \f[V].class\f[R] file, a
-directory, a JAR file, or it can be a fully qualified class name to
-analyze all class files.
-The options determine the output.
-By default, the \f[V]jdeps\f[R] command writes the dependencies to the
-system output.
-The command can generate the dependencies in DOT language (see the
-\f[V]-dotoutput\f[R] option).
-.SH POSSIBLE OPTIONS
-.TP
-\f[V]-?\f[R] or \f[V]-h\f[R] or \f[V]--help\f[R]
-Prints the help message.
-.TP
-\f[V]-dotoutput\f[R] \f[I]dir\f[R] or \f[V]--dot-output\f[R] \f[I]dir\f[R]
-Specifies the destination directory for DOT file output.
-If this option is specified, then the \f[V]jdeps\f[R]command generates
-one \f[V].dot\f[R] file for each analyzed archive named
-\f[V]archive-file-name.dot\f[R] that lists the dependencies, and also a
-summary file named \f[V]summary.dot\f[R] that lists the dependencies
-among the archive files.
-.TP
-\f[V]-s\f[R] or \f[V]-summary\f[R]
-Prints a dependency summary only.
-.TP
-\f[V]-v\f[R] or \f[V]-verbose\f[R]
-Prints all class-level dependencies.
-This is equivalent to
-.RS
-.RS
-.PP
-\f[V]-verbose:class -filter:none\f[R]
-.RE
-.RE
-.TP
-\f[V]-verbose:package\f[R]
-Prints package-level dependencies excluding, by default, dependences
-within the same package.
-.TP
-\f[V]-verbose:class\f[R]
-Prints class-level dependencies excluding, by default, dependencies
-within the same archive.
-.TP
-\f[V]-apionly\f[R] or \f[V]--api-only\f[R]
-Restricts the analysis to APIs, for example, dependences from the
-signature of \f[V]public\f[R] and \f[V]protected\f[R] members of public
-classes including field type, method parameter types, returned type, and
-checked exception types.
-.TP
-\f[V]-jdkinternals\f[R] or \f[V]--jdk-internals\f[R]
-Finds class-level dependences in the JDK internal APIs.
-By default, this option analyzes all classes specified in the
-\f[V]--classpath\f[R] option and input files unless you specified the
-\f[V]-include\f[R] option.
-You can\[aq]t use this option with the \f[V]-p\f[R], \f[V]-e\f[R], and
-\f[V]-s\f[R] options.
-.RS
-.PP
-\f[B]Warning\f[R]: The JDK internal APIs are inaccessible.
-.RE
-.TP
-\f[V]-cp\f[R] \f[I]path\f[R], \f[V]-classpath\f[R] \f[I]path\f[R], or \f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies where to find class files.
-.TP
-\f[V]--module-path\f[R] \f[I]module-path\f[R]
-Specifies the module path.
-.TP
-\f[V]--upgrade-module-path\f[R] \f[I]module-path\f[R]
-Specifies the upgrade module path.
-.TP
-\f[V]--system\f[R] \f[I]java-home\f[R]
-Specifies an alternate system module path.
-.TP
-\f[V]--add-modules\f[R] \f[I]module-name\f[R][\f[V],\f[R] \f[I]module-name\f[R]...]
-Adds modules to the root set for analysis.
-.TP
-\f[V]--multi-release\f[R] \f[I]version\f[R]
-Specifies the version when processing multi-release JAR files.
-\f[I]version\f[R] should be an integer >=9 or base.
-.TP
-\f[V]-q\f[R] or \f[V]-quiet\f[R]
-Doesn\[aq]t show missing dependencies from
-\f[V]-generate-module-info\f[R] output.
-.TP
-\f[V]-version\f[R] or \f[V]--version\f[R]
-Prints version information.
-.SH MODULE DEPENDENCE ANALYSIS OPTIONS
-.TP
-\f[V]-m\f[R] \f[I]module-name\f[R] or \f[V]--module\f[R] \f[I]module-name\f[R]
-Specifies the root module for analysis.
-.TP
-\f[V]--generate-module-info\f[R] \f[I]dir\f[R]
-Generates \f[V]module-info.java\f[R] under the specified directory.
-The specified JAR files will be analyzed.
-This option cannot be used with \f[V]--dot-output\f[R] or
-\f[V]--class-path\f[R] options.
-Use the \f[V]--generate-open-module\f[R] option for open modules.
-.TP
-\f[V]--generate-open-module\f[R] \f[I]dir\f[R]
-Generates \f[V]module-info.java\f[R] for the specified JAR files under
-the specified directory as open modules.
-This option cannot be used with the \f[V]--dot-output\f[R] or
-\f[V]--class-path\f[R] options.
-.TP
-\f[V]--check\f[R] \f[I]module-name\f[R] [\f[V],\f[R] \f[I]module-name\f[R]...]
-Analyzes the dependence of the specified modules.
-It prints the module descriptor, the resulting module dependences after
-analysis and the graph after transition reduction.
-It also identifies any unused qualified exports.
-.TP
-\f[V]--list-deps\f[R]
-Lists the module dependences and also the package names of JDK internal
-APIs (if referenced).
-This option transitively analyzes libraries on class path and module
-path if referenced.
-Use \f[V]--no-recursive\f[R] option for non-transitive dependency
-analysis.
-.TP
-\f[V]--list-reduced-deps\f[R]
-Same as \f[V]--list-deps\f[R] without listing the implied reads edges
-from the module graph.
-If module M1 reads M2, and M2 requires transitive on M3, then M1 reading
-M3 is implied and is not shown in the graph.
-.TP
-\f[V]--print-module-deps\f[R]
-Same as \f[V]--list-reduced-deps\f[R] with printing a comma-separated
-list of module dependences.
-The output can be used by \f[V]jlink --add-modules\f[R] to create a
-custom image that contains those modules and their transitive
-dependences.
-.TP
-\f[V]--ignore-missing-deps\f[R]
-Ignore missing dependences.
-.SH OPTIONS TO FILTER DEPENDENCES
-.TP
-\f[V]-p\f[R] \f[I]pkg_name\f[R], \f[V]-package\f[R] \f[I]pkg_name\f[R], or \f[V]--package\f[R] \f[I]pkg_name\f[R]
-Finds dependences matching the specified package name.
-You can specify this option multiple times for different packages.
-The \f[V]-p\f[R] and \f[V]-e\f[R] options are mutually exclusive.
-.TP
-\f[V]-e\f[R] \f[I]regex\f[R], \f[V]-regex\f[R] \f[I]regex\f[R], or \f[V]--regex\f[R] \f[I]regex\f[R]
-Finds dependences matching the specified pattern.
-The \f[V]-p\f[R] and \f[V]-e\f[R] options are mutually exclusive.
-.TP
-\f[V]--require\f[R] \f[I]module-name\f[R]
-Finds dependences matching the given module name (may be given multiple
-times).
-The \f[V]--package\f[R], \f[V]--regex\f[R], and \f[V]--require\f[R]
-options are mutually exclusive.
-.TP
-\f[V]-f\f[R] \f[I]regex\f[R] or \f[V]-filter\f[R] \f[I]regex\f[R]
-Filters dependences matching the given pattern.
-If give multiple times, the last one will be selected.
-.TP
-\f[V]-filter:package\f[R]
-Filters dependences within the same package.
-This is the default.
-.TP
-\f[V]-filter:archive\f[R]
-Filters dependences within the same archive.
-.TP
-\f[V]-filter:module\f[R]
-Filters dependences within the same module.
-.TP
-\f[V]-filter:none\f[R]
-No \f[V]-filter:package\f[R] and \f[V]-filter:archive\f[R] filtering.
-Filtering specified via the \f[V]-filter\f[R] option still applies.
-.TP
-\f[V]--missing-deps\f[R]
-Finds missing dependences.
-This option cannot be used with \f[V]-p\f[R], \f[V]-e\f[R] and
-\f[V]-s\f[R] options.
-.SH OPTIONS TO FILTER CLASSES TO BE ANALYZED
-.TP
-\f[V]-include\f[R] \f[I]regex\f[R]
-Restricts analysis to the classes matching pattern.
-This option filters the list of classes to be analyzed.
-It can be used together with \f[V]-p\f[R] and \f[V]-e\f[R], which apply
-the pattern to the dependencies.
-.TP
-\f[V]-R\f[R] or \f[V]--recursive\f[R]
-Recursively traverses all run-time dependences.
-The \f[V]-R\f[R] option implies \f[V]-filter:none\f[R].
-If \f[V]-p\f[R], \f[V]-e\f[R], or \f[V]-f\f[R] options are specified,
-only the matching dependences are analyzed.
-.TP
-\f[V]--no-recursive\f[R]
-Do not recursively traverse dependences.
-.TP
-\f[V]-I\f[R] or \f[V]--inverse\f[R]
-Analyzes the dependences per other given options and then finds all
-artifacts that directly and indirectly depend on the matching nodes.
-This is equivalent to the inverse of the compile-time view analysis and
-the print dependency summary.
-This option must be used with the \f[V]--require\f[R],
-\f[V]--package\f[R], or \f[V]--regex\f[R] options.
-.TP
-\f[V]--compile-time\f[R]
-Analyzes the compile-time view of transitive dependencies, such as the
-compile-time view of the \f[V]-R\f[R] option.
-Analyzes the dependences per other specified options.
-If a dependency is found from a directory, a JAR file or a module, all
-classes in that containing archive are analyzed.
-.SH EXAMPLE OF ANALYZING DEPENDENCIES
-.PP
-The following example demonstrates analyzing the dependencies of the
-\f[V]Notepad.jar\f[R] file.
-.PP
-\f[B]Linux and macOS:\f[R]
-.IP
-.nf
-\f[CB]
-$ jdeps demo/jfc/Notepad/Notepad.jar
-Notepad.jar -> java.base
-Notepad.jar -> java.desktop
-Notepad.jar -> java.logging
-   <unnamed> (Notepad.jar)
-      -> java.awt
-      -> java.awt.event
-      -> java.beans
-      -> java.io
-      -> java.lang
-      -> java.net
-      -> java.util
-      -> java.util.logging
-      -> javax.swing
-      -> javax.swing.border
-      -> javax.swing.event
-      -> javax.swing.text
-      -> javax.swing.tree
-      -> javax.swing.undo
-\f[R]
-.fi
-.PP
-\f[B]Windows:\f[R]
-.IP
-.nf
-\f[CB]
-C:\[rs]Java\[rs]jdk1.9.0>jdeps demo\[rs]jfc\[rs]Notepad\[rs]Notepad.jar
-Notepad.jar -> java.base
-Notepad.jar -> java.desktop
-Notepad.jar -> java.logging
-   <unnamed> (Notepad.jar)
-      -> java.awt
-      -> java.awt.event
-      -> java.beans
-      -> java.io
-      -> java.lang
-      -> java.net
-      -> java.util
-      -> java.util.logging
-      -> javax.swing
-      -> javax.swing.border
-      -> javax.swing.event
-      -> javax.swing.text
-      -> javax.swing.tree
-      -> javax.swing.undo
-\f[R]
-.fi
-.SH EXAMPLE USING THE --INVERSE OPTION
-.IP
-.nf
-\f[CB]
- $ jdeps --inverse --require java.xml.bind
-Inverse transitive dependences on [java.xml.bind]
-java.xml.bind <- java.se.ee
-java.xml.bind <- jdk.xml.ws
-java.xml.bind <- java.xml.ws <- java.se.ee
-java.xml.bind <- java.xml.ws <- jdk.xml.ws
-java.xml.bind <- jdk.xml.bind <- jdk.xml.ws
-\f[R]
-.fi
diff --git a/src/jdk.jdeps/share/man/jdeps.md b/src/jdk.jdeps/share/man/jdeps.md
new file mode 100644
index 00000000000..cb936bf3e01
--- /dev/null
+++ b/src/jdk.jdeps/share/man/jdeps.md
@@ -0,0 +1,297 @@
+---
+# Copyright (c) 2013, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JDEPS(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jdeps - launch the Java class dependency analyzer
+
+## Synopsis
+
+`jdeps` \[*options*\] *path* ...
+
+*options*
+:   Command-line options. For detailed descriptions of the options that can be
+    used, see
+
+    -   [Possible Options]
+
+    -   [Module Dependence Analysis Options]
+
+    -   [Options to Filter Dependences]
+
+    -   [Options to Filter Classes to be Analyzed]
+
+*path*
+:   A pathname to the `.class` file, directory, or JAR file to analyze.
+
+## Description
+
+The `jdeps` command shows the package-level or class-level dependencies of Java
+class files. The input class can be a path name to a `.class` file, a
+directory, a JAR file, or it can be a fully qualified class name to analyze all
+class files. The options determine the output. By default, the `jdeps` command
+writes the dependencies to the system output. The command can generate the
+dependencies in DOT language (see the `-dotoutput` option).
+
+## Possible Options
+
+`-?` or `-h` or `--help`
+:   Prints the help message.
+
+`-dotoutput` *dir* or `--dot-output` *dir*
+:   Specifies the destination directory for DOT file output. If this option is
+    specified, then the `jdeps`command generates one `.dot` file for each
+    analyzed archive named `archive-file-name.dot` that lists the dependencies,
+    and also a summary file named `summary.dot` that lists the dependencies
+    among the archive files.
+
+`-s` or `-summary`
+:   Prints a dependency summary only.
+
+`-v` or `-verbose`
+:   Prints all class-level dependencies. This is equivalent to
+
+    >   `-verbose:class -filter:none`
+
+`-verbose:package`
+:   Prints package-level dependencies excluding, by default, dependences within
+    the same package.
+
+`-verbose:class`
+:   Prints class-level dependencies excluding, by default, dependencies within
+    the same archive.
+
+`-apionly` or `--api-only`
+:   Restricts the analysis to APIs, for example, dependences from the signature
+    of `public` and `protected` members of public classes including field type,
+    method parameter types, returned type, and checked exception types.
+
+`-jdkinternals` or `--jdk-internals`
+:   Finds class-level dependences in the JDK internal APIs. By default, this
+    option analyzes all classes specified in the `--classpath` option and input
+    files unless you specified the `-include` option. You can't use this option
+    with the `-p`, `-e`, and `-s` options.
+
+    **Warning**: The JDK internal APIs are inaccessible.
+
+`-cp` *path*, `-classpath` *path*, or `--class-path` *path*
+:   Specifies where to find class files.
+
+`--module-path` *module-path*
+:   Specifies the module path.
+
+`--upgrade-module-path` *module-path*
+:   Specifies the upgrade module path.
+
+`--system` *java-home*
+:   Specifies an alternate system module path.
+
+`--add-modules` *module-name*\[`,` *module-name*...\]
+:   Adds modules to the root set for analysis.
+
+`--multi-release` *version*
+:   Specifies the version when processing multi-release JAR files. *version*
+    should be an integer \>=9 or base.
+
+`-q` or `-quiet`
+:   Doesn't show missing dependencies from `-generate-module-info` output.
+
+`-version` or `--version`
+:   Prints version information.
+
+## Module Dependence Analysis Options
+
+`-m` *module-name* or `--module` *module-name*
+:   Specifies the root module for analysis.
+
+`--generate-module-info` *dir*
+:   Generates `module-info.java` under the specified directory. The specified
+    JAR files will be analyzed. This option cannot be used with `--dot-output`
+    or `--class-path` options. Use the `--generate-open-module` option for open
+    modules.
+
+`--generate-open-module` *dir*
+:   Generates `module-info.java` for the specified JAR files under the
+    specified directory as open modules. This option cannot be used with the
+    `--dot-output` or `--class-path` options.
+
+`--check` *module-name* \[`,` *module-name*...\]
+:   Analyzes the dependence of the specified modules. It prints the module
+    descriptor, the resulting module dependences after analysis and the graph
+    after transition reduction. It also identifies any unused qualified
+    exports.
+
+`--list-deps`
+:   Lists the module dependences and also the package names of JDK internal
+    APIs (if referenced).  This option transitively analyzes libraries on
+    class path and module path if referenced.  Use `--no-recursive` option for
+    non-transitive dependency analysis.
+
+`--list-reduced-deps`
+:   Same as `--list-deps` without listing the implied reads edges from the
+    module graph. If module M1 reads M2, and M2 requires transitive on M3, then
+    M1 reading M3 is implied and is not shown in the graph.
+
+`--print-module-deps`
+:   Same as `--list-reduced-deps` with printing a comma-separated list of
+    module dependences. The output can be used by `jlink --add-modules` to
+    create a custom image that contains those modules and their transitive
+    dependences.
+
+`--ignore-missing-deps`
+:   Ignore missing dependences.
+
+## Options to Filter Dependences
+
+`-p` *pkg\_name*, `-package` *pkg\_name*, or `--package` *pkg\_name*
+:   Finds dependences matching the specified package name. You can specify this
+    option multiple times for different packages. The `-p` and `-e` options are
+    mutually exclusive.
+
+`-e` *regex*, `-regex` *regex*, or `--regex` *regex*
+:   Finds dependences matching the specified pattern. The `-p` and `-e` options
+    are mutually exclusive.
+
+`--require` *module-name*
+:   Finds dependences matching the given module name (may be given multiple
+    times). The `--package`, `--regex`, and `--require` options are mutually
+    exclusive.
+
+`-f` *regex* or `-filter` *regex*
+:   Filters dependences matching the given pattern. If give multiple times, the
+    last one will be selected.
+
+`-filter:package`
+:   Filters dependences within the same package. This is the default.
+
+`-filter:archive`
+:   Filters dependences within the same archive.
+
+`-filter:module`
+:   Filters dependences within the same module.
+
+`-filter:none`
+:   No `-filter:package` and `-filter:archive` filtering. Filtering specified
+    via the `-filter` option still applies.
+
+`--missing-deps`
+:   Finds missing dependences.  This option cannot be used with `-p`, `-e` and
+    `-s` options.
+
+## Options to Filter Classes to be Analyzed
+
+`-include` *regex*
+:   Restricts analysis to the classes matching pattern. This option filters the
+    list of classes to be analyzed. It can be used together with `-p` and `-e`,
+    which apply the pattern to the dependencies.
+
+`-R` or `--recursive`
+:   Recursively traverses all run-time dependences. The `-R` option implies
+    `-filter:none`. If `-p`, `-e`, or `-f` options are specified, only the
+    matching dependences are analyzed.
+
+`--no-recursive`
+:   Do not recursively traverse dependences.
+
+`-I` or `--inverse`
+:   Analyzes the dependences per other given options and then finds all
+    artifacts that directly and indirectly depend on the matching nodes. This
+    is equivalent to the inverse of the compile-time view analysis and the
+    print dependency summary. This option must be used with the `--require`,
+    `--package`, or `--regex` options.
+
+`--compile-time`
+:   Analyzes the compile-time view of transitive dependencies, such as the
+    compile-time view of the `-R` option. Analyzes the dependences per other
+    specified options. If a dependency is found from a directory, a JAR file or
+    a module, all classes in that containing archive are analyzed.
+
+## Example of Analyzing Dependencies
+
+The following example demonstrates analyzing the dependencies of the
+`Notepad.jar` file.
+
+**Linux and macOS:**
+
+```
+$ jdeps demo/jfc/Notepad/Notepad.jar
+Notepad.jar -> java.base
+Notepad.jar -> java.desktop
+Notepad.jar -> java.logging
+   <unnamed> (Notepad.jar)
+      -> java.awt
+      -> java.awt.event
+      -> java.beans
+      -> java.io
+      -> java.lang
+      -> java.net
+      -> java.util
+      -> java.util.logging
+      -> javax.swing
+      -> javax.swing.border
+      -> javax.swing.event
+      -> javax.swing.text
+      -> javax.swing.tree
+      -> javax.swing.undo
+```
+
+**Windows:**
+
+```
+C:\Java\jdk1.9.0>jdeps demo\jfc\Notepad\Notepad.jar
+Notepad.jar -> java.base
+Notepad.jar -> java.desktop
+Notepad.jar -> java.logging
+   <unnamed> (Notepad.jar)
+      -> java.awt
+      -> java.awt.event
+      -> java.beans
+      -> java.io
+      -> java.lang
+      -> java.net
+      -> java.util
+      -> java.util.logging
+      -> javax.swing
+      -> javax.swing.border
+      -> javax.swing.event
+      -> javax.swing.text
+      -> javax.swing.tree
+      -> javax.swing.undo
+```
+
+## Example Using the --inverse Option
+
+```
+ $ jdeps --inverse --require java.xml.bind
+Inverse transitive dependences on [java.xml.bind]
+java.xml.bind <- java.se.ee
+java.xml.bind <- jdk.xml.ws
+java.xml.bind <- java.xml.ws <- java.se.ee
+java.xml.bind <- java.xml.ws <- jdk.xml.ws
+java.xml.bind <- jdk.xml.bind <- jdk.xml.ws
+```
diff --git a/src/jdk.jdeps/share/man/jnativescan.1 b/src/jdk.jdeps/share/man/jnativescan.1
deleted file mode 100644
index ff7f18277f2..00000000000
--- a/src/jdk.jdeps/share/man/jnativescan.1
+++ /dev/null
@@ -1,220 +0,0 @@
-.\" Copyright (c) 2024, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JNATIVESCAN" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jnativescan - static analysis tool that scans one or more jar files for
-uses of native functionalities, such as restricted method calls or
-\f[V]native\f[R] method declarations.
-.SH SYNOPSIS
-.PP
-\f[V]jnativescan\f[R] [\f[I]options\f[R]]
-.TP
-\f[I]options\f[R]
-See \f[B]Options for the jnativescan Command\f[R]
-.SH DESCRIPTION
-.PP
-The \f[V]jnative\f[R] tool is a static analysis tool provided by the JDK
-that scans a JAR file for uses of native functionalities, such as
-restricted method calls or \f[V]native\f[R] method declarations.
-.PP
-\f[V]jnativescan\f[R] accepts a runtime class path and module path
-configuration, as well as a set of root modules, and a target release.
-It scans the jars on the class and module paths, and reports uses of
-native functionalities either in a tree like structure, which also
-identifies that calling classes and methods, or as a list of module
-names when the \f[V]--print-native-access\f[R] flag is specified.
-.SH OPTIONS FOR THE JNATIVESCAN COMMAND
-.PP
-The following options are available:
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Used to specify a list of paths pointing to jar files to be scanned.
-.PP
-All jar files specified through this list will be scanned.
-If a jar file contains a \f[V]Class-Path\f[R] attribute in its manifest,
-jar files listed there will be scanned as well.
-Jar files listed in the \f[V]Class-Path\f[R] manifest attribute that can
-not be found are ignored.
-All the jar files found are treated as if they belonged to the unnamed
-module.
-.TP
-\f[V]--module-path\f[R] \f[I]path\f[R]
-Used to specify a list of paths pointing to jar files or directories
-containing jar files, that the tool can use to find modules that need to
-be scanned.
-The list of jar files that will be scanned depends on the
-\f[V]--add-modules\f[R] option.
-.RS
-.PP
-For both the \f[V]--class-path\f[R] and \f[V]--module-path\f[R] options,
-\f[I]path\f[R] should be a search path that consists of one or more jar
-files, separated by the system-specific path separator.
-For example:
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]--class-path /some/foo.jar:/another/different/bar.jar\f[R]
-.RE
-.RE
-.PP
-\f[B]Note:\f[R]
-.PP
-On Windows, use a semicolon (\f[V];\f[R]) as the separator instead of a
-colon (\f[V]:\f[R]).
-.IP \[bu] 2
-\f[B]Windows:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]--class-path C:\[rs]some\[rs]foo.jar;C:\[rs]another\[rs]different\[rs]bar.jar\f[R]
-.RE
-.RE
-.RE
-.TP
-\f[V]--add-modules\f[R] \f[I]module[,module...]\f[R]
-Used to specify a comma-separated list of module names that indicate the
-root modules to scan.
-All the root modules will be scanned, as well as any modules that they
-depend on.
-This includes dependencies on service implementations specified through
-the \f[V]uses\f[R] directive in a module\[aq]s \f[V]module-info\f[R]
-file.
-All modules found on the module path that provide an implementation of
-such a service will be scanned as well.
-.TP
-\f[V]--release\f[R] \f[I]version\f[R]
-Used to specify the Java SE release that specifies the set of restricted
-methods to scan for.
-For multi-release jar files, this option also indicates the version of
-class file that should be loaded from the jar.
-This option should be set to the version of the runtime under which the
-application is eventually intended to be run.
-If this flag is omitted, the version of \f[V]jnativescan\f[R] is used as
-release version, which is the same as the version of the JDK that the
-tool belongs to.
-.TP
-\f[V]--print-native-access\f[R]
-Print a comma-separated list of module names that use native
-functionalities, instead of the default tree structure.
-.TP
-\f[V]--help\f[R] or \f[V]-h\f[R]
-Prints out a full help message.
-.TP
-\f[V]--version\f[R]
-Prints out the abbreviated version string of the tool.
-.SH EXAMPLE OF \f[V]jnativescan\f[R] USE
-.PP
-\f[V]jnativescan\f[R] accepts a runtime configuration in the form of a
-class path, module path, set of root modules, and a target release
-version.
-For the class path, the tool will scan all jar files, including those
-found recursively through the \f[V]Class-Path\f[R] manifest attribute.
-For the module path, the tool scans all root modules specified through
-\f[V]--add-modules\f[R], and any (transitive) dependence of the root
-modules, including any modules that contain service implementations that
-are used by a scanned module.
-.PP
-By default, the tool prints out which jars, classes, and methods use
-native functionalities, in a tree-like structure.
-The following is an example output:
-.IP
-.nf
-\f[CB]
-$ jnativescan --class-path app.jar
-app.jar (ALL-UNNAMED):
-  foo.Main:
-    foo.Main::main(String[])void references restricted methods:
-      java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment
-    foo.Main::nativeMethod()void is a native method declaration
-\f[R]
-.fi
-.PP
-\f[V]app.jar (ALL-UNNAMED)\f[R] is the path to the jar file, with the
-module name in parentheses behind it.
-Since in this case the jar file appears on the class path,
-\f[V]ALL-UNNAMED\f[R] is printed to indicate the unnamed module.
-The second line of the output, \f[V]foo.Main\f[R], indicates that
-methods using native functionalities were found in the
-\f[V]foo.Main\f[R] class.
-The next line:
-.IP
-.nf
-\f[CB]
-    foo.Main::main(String[])void references restricted methods:
-\f[R]
-.fi
-.PP
-Indicates that the \f[V]main(String[])\f[R] method in the
-\f[V]foo.Main\f[R] class references a restricted method, which is listed
-on the following line as:
-.IP
-.nf
-\f[CB]
-      java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment
-\f[R]
-.fi
-.PP
-Lastly, the text:
-.IP
-.nf
-\f[CB]
-    foo.Main::nativeMethod()void is a native method declaration
-\f[R]
-.fi
-.PP
-Indicates that the \f[V]foo.Main\f[R] class contains a declaration of a
-\f[V]native\f[R] method named \f[V]nativeMethod\f[R].
-.PP
-If we add \f[V]--print-native-access\f[R] to the example command line,
-we instead get a list of the names of modules that contain accesses to
-native functionalities:
-.IP
-.nf
-\f[CB]
-$ jnativescan --class-path app.jar --print-native-access
-ALL-UNNAMED
-\f[R]
-.fi
-.PP
-In this case the output consists of just \f[V]ALL-UNNAMED\f[R], which
-indicates a jar file on the class path, that is, in the unnamed module,
-contains an access to native functionalities.
diff --git a/src/jdk.jdeps/share/man/jnativescan.md b/src/jdk.jdeps/share/man/jnativescan.md
new file mode 100644
index 00000000000..73c2429fc89
--- /dev/null
+++ b/src/jdk.jdeps/share/man/jnativescan.md
@@ -0,0 +1,175 @@
+---
+# Copyright (c) 2024, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JNATIVESCAN(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jnativescan - static analysis tool that scans one or more jar files for uses of
+native functionalities, such as restricted method calls or `native` method declarations.
+
+## Synopsis
+
+`jnativescan` \[*options*\]
+
+*options*
+:   See [Options for the jnativescan Command]
+
+## Description
+
+The `jnative` tool is a static analysis tool provided by the JDK that scans a
+JAR file for uses of native functionalities, such as restricted method calls
+or `native` method declarations.
+
+`jnativescan` accepts a runtime class path and module path configuration, as
+well as a set of root modules, and a target release. It scans the jars on the
+class and module paths, and reports uses of native functionalities either in a tree
+like structure, which also identifies that calling classes and methods, or as a list
+of module names when the `--print-native-access` flag is specified.
+
+## Options for the jnativescan Command
+
+The following options are available:
+
+`--class-path` *path*
+:   Used to specify a list of paths pointing to jar files to be scanned.
+
+All jar files specified through this list will be scanned. If a jar file
+contains a `Class-Path` attribute in its manifest, jar files listed there
+will be scanned as well. Jar files listed in the `Class-Path` manifest
+attribute that can not be found are ignored. All the jar files found are
+treated as if they belonged to the unnamed module.
+
+`--module-path` *path*
+:   Used to specify a list of paths pointing to jar files or directories
+containing jar files, that the tool can use to find modules that need
+to be scanned. The list of jar files that will be scanned depends on the
+`--add-modules` option.
+
+    For both the `--class-path` and `--module-path` options, *path* should
+    be a search path that consists of one or more jar files, separated by
+    the system-specific path separator. For example:
+
+    -   **Linux and macOS:**
+
+        >   `--class-path /some/foo.jar:/another/different/bar.jar`
+
+    **Note:**
+
+    On Windows, use a semicolon (`;`) as the separator instead of a colon
+    (`:`).
+
+    -   **Windows:**
+
+        >   `--class-path C:\some\foo.jar;C:\another\different\bar.jar`
+
+`--add-modules` *module[,module...]*
+:   Used to specify a comma-separated list of module names that indicate
+the root modules to scan. All the root modules will be scanned,
+as well as any modules that they depend on. This includes dependencies on
+service implementations specified through the `uses` directive in a module's
+`module-info` file. All modules found on the module path that provide an
+implementation of such a service will be scanned as well.
+
+`--release` *version*
+:   Used to specify the Java SE release that specifies the set of restricted
+methods to scan for. For multi-release jar files, this option also indicates
+the version of class file that should be loaded from the jar. This option
+should be set to the version of the runtime under which the application is
+eventually intended to be run. If this flag is omitted, the version of
+`jnativescan` is used as release version, which is the same as the version of
+the JDK that the tool belongs to.
+
+`--print-native-access`
+:   Print a comma-separated list of module names that use native functionalities,
+instead of the default tree structure.
+
+`--help` or `-h`
+:   Prints out a full help message.
+
+`--version`
+:   Prints out the abbreviated version string of the tool.
+
+## Example of `jnativescan` use
+
+`jnativescan` accepts a runtime configuration in the form of a class path, module
+path, set of root modules, and a target release version. For the class path, the
+tool will scan all jar files, including those found recursively through the
+`Class-Path` manifest attribute. For the module path, the tool scans all root
+modules specified through `--add-modules`, and any (transitive) dependence of
+the root modules, including any modules that contain service implementations that
+are used by a scanned module.
+
+By default, the tool prints out which jars, classes, and methods use native
+functionalities, in a tree-like structure. The following is an example output:
+
+```
+$ jnativescan --class-path app.jar
+app.jar (ALL-UNNAMED):
+  foo.Main:
+    foo.Main::main(String[])void references restricted methods:
+      java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment
+    foo.Main::nativeMethod()void is a native method declaration
+```
+
+`app.jar (ALL-UNNAMED)` is the path to the jar file, with the module name in
+parentheses behind it. Since in this case the jar file appears on the class
+path, `ALL-UNNAMED` is printed to indicate the unnamed module. The second line
+of the output, `foo.Main`, indicates that methods using native functionalities
+were found in the `foo.Main` class. The next line:
+
+```
+    foo.Main::main(String[])void references restricted methods:
+```
+
+Indicates that the `main(String[])` method in the `foo.Main` class references
+a restricted method, which is listed on the following line as:
+
+```
+      java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment
+```
+
+Lastly, the text:
+
+```
+    foo.Main::nativeMethod()void is a native method declaration
+```
+
+Indicates that the `foo.Main` class contains a declaration of a `native`
+method named `nativeMethod`.
+
+If we add `--print-native-access` to the example command line, we instead
+get a list of the names of modules that contain accesses to native
+functionalities:
+
+```
+$ jnativescan --class-path app.jar --print-native-access
+ALL-UNNAMED
+```
+
+In this case the output consists of just `ALL-UNNAMED`, which indicates
+a jar file on the class path, that is, in the unnamed module, contains an access
+to native functionalities.
diff --git a/src/jdk.jdi/share/man/jdb.1 b/src/jdk.jdi/share/man/jdb.1
deleted file mode 100644
index 88097ffeae4..00000000000
--- a/src/jdk.jdi/share/man/jdb.1
+++ /dev/null
@@ -1,277 +0,0 @@
-.\" Copyright (c) 1995, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JDB" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jdb - find and fix bugs in Java platform programs
-.SH SYNOPSIS
-.PP
-\f[V]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
-[\f[I]arguments\f[R]]
-.TP
-\f[I]options\f[R]
-This represents the \f[V]jdb\f[R] command-line options.
-See \f[B]Options for the jdb command\f[R].
-.TP
-\f[I]classname\f[R]
-This represents the name of the main class to debug.
-.TP
-\f[I]arguments\f[R]
-This represents the arguments that are passed to the \f[V]main()\f[R]
-method of the class.
-.SH DESCRIPTION
-.PP
-The Java Debugger (JDB) is a simple command-line debugger for Java
-classes.
-The \f[V]jdb\f[R] command and its options call the JDB.
-The \f[V]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[V]jdb\f[R] command for the \f[V]java\f[R]
-command in the command line.
-For example, if your application\[aq]s main class is \f[V]MyClass\f[R],
-then use the following command to debug it under the JDB:
-.RS
-.PP
-\f[V]jdb MyClass\f[R]
-.RE
-.PP
-When started this way, the \f[V]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[V]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[V]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[V]java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass\f[R]
-.RE
-.PP
-You can then attach the \f[V]jdb\f[R] command to the JVM with the
-following command:
-.RS
-.PP
-\f[V]jdb -attach 8000\f[R]
-.RE
-.PP
-8000 is the address of the running JVM.
-.PP
-The \f[V]MyClass\f[R] argument isn\[aq]t specified in the \f[V]jdb\f[R]
-command line in this case because the \f[V]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[V]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[V]stop at MyClass:22\f[R] sets a breakpoint at the first
-instruction for line 22 of the source file containing \f[V]MyClass\f[R].
-.IP \[bu] 2
-The command \f[V]stop in java.lang.String.length\f[R] sets a breakpoint
-at the beginning of the method \f[V]java.lang.String.length\f[R].
-.IP \[bu] 2
-The command \f[V]stop in MyClass.<clinit>\f[R] uses \f[V]<clinit>\f[R]
-to identify the static initialization code for \f[V]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[V]MyClass.myMethod(int,java.lang.String)\f[R] or
-\f[V]MyClass.myMethod()\f[R].
-.PP
-The \f[V]clear\f[R] command removes breakpoints using the following
-syntax: \f[V]clear MyClass:45\f[R].
-Using the \f[V]clear\f[R] or \f[V]stop\f[R] command with no argument
-displays a list of all breakpoints currently set.
-The \f[V]cont\f[R] command continues execution.
-.SH STEPPING
-.PP
-The \f[V]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[V]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[V]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[V]jdb\f[R] command to diagnose the cause of the
-exception.
-.PP
-Use the \f[V]catch\f[R] command to cause the debugged application to
-stop at other thrown exceptions, for example:
-\f[V]catch java.io.FileNotFoundException\f[R] or \f[V]catch\f[R]
-\f[V]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[V]ignore\f[R] command negates the effect of an earlier
-\f[V]catch\f[R] command.
-The \f[V]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[V]jdb\f[R] command instead of the \f[V]java\f[R]
-command on the command line, the \f[V]jdb\f[R] command accepts many of
-the same options as the \f[V]java\f[R] command.
-.PP
-The following options are accepted by the \f[V]jdb\f[R] command:
-.TP
-\f[V]-help\f[R]
-Displays a help message.
-.TP
-\f[V]-sourcepath\f[R] \f[I]dir1\f[R]\f[V]:\f[R]\f[I]dir2\f[R]\f[V]:\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[V].\f[R]).
-.TP
-\f[V]-attach\f[R] \f[I]address\f[R]
-Attaches the debugger to a running JVM with the default connection
-mechanism.
-.TP
-\f[V]-listen\f[R] \f[I]address\f[R]
-Waits for a running JVM to connect to the specified address with a
-standard connector.
-.TP
-\f[V]-listenany\f[R]
-Waits for a running JVM to connect at any available address using a
-standard connector.
-.TP
-\f[V]-launch\f[R]
-Starts the debugged application immediately upon startup of the
-\f[V]jdb\f[R] command.
-The \f[V]-launch\f[R] option removes the need for the \f[V]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[V]cont\f[R] command to continue execution.
-.TP
-\f[V]-listconnectors\f[R]
-Lists the connectors available in this JVM.
-.TP
-\f[V]-connect\f[R] \f[I]connector-name\f[R]\f[V]:\f[R]\f[I]name1\f[R]\f[V]=\f[R]\f[I]value1\f[R]....
-Connects to the target JVM with the named connector and listed argument
-values.
-.TP
-\f[V]-dbgtrace\f[R] [\f[I]flags\f[R]]
-Prints information for debugging the \f[V]jdb\f[R] command.
-.TP
-\f[V]-tclient\f[R]
-Runs the application in the Java HotSpot VM client.
-.TP
-\f[V]-trackallthreads\f[R]
-Track all threads as they are created, including virtual threads.
-See \f[B]Working With Virtual Threads\f[R] below.
-.TP
-\f[V]-tserver\f[R]
-Runs the application in the Java HotSpot VM server.
-.TP
-\f[V]-J\f[R]\f[I]option\f[R]
-Passes \f[I]option\f[R] to the JDB JVM, where option is one of the
-options described on the reference page for the Java application
-launcher.
-For example, \f[V]-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].
-.PP
-The following options are forwarded to the debuggee process:
-.TP
-\f[V]-R\f[R]\f[I]option\f[R]
-Passes \f[I]option\f[R] to the debuggee JVM, where option is one of the
-options described on the reference page for the Java application
-launcher.
-For example, \f[V]-R-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].
-.TP
-\f[V]-v\f[R] or \f[V]-verbose\f[R][\f[V]:\f[R]\f[I]class\f[R]|\f[V]gc\f[R]|\f[V]jni\f[R]]
-Turns on the verbose mode.
-.TP
-\f[V]-D\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R]
-Sets a system property.
-.TP
-\f[V]-classpath\f[R] \f[I]dir\f[R]
-Lists directories separated by colons in which to look for classes.
-.TP
-\f[V]-X\f[R] \f[I]option\f[R]
-A nonstandard target JVM option.
-.PP
-Other options are supported to provide alternate mechanisms for
-connecting the debugger to the JVM that it\[aq]s to debug.
-.SH WORKING WITH VIRTUAL THREADS
-.PP
-Often virtual theads are created in such large numbers and frequency
-that they can overwhelm a debugger.
-For this reason by default JDB does not keep track of virtual threads as
-they are created.
-It will only keep track of virtual threads that an event has arrived on,
-such as a breakpoint event.
-The \f[V]-trackallthreads\f[R] option can be used to make JDB track all
-virtual threads as they are created.
-.PP
-When JDB first connects, it requests a list of all known threads from
-the Debug Agent.
-By default the debug agent does not return any virtual threads in this
-list, once again because the list could be so large that it overwhelms
-the debugger.
-The Debug Agent has an \f[V]includevirtualthreads\f[R] option that can
-be enabled to change this behavior so all known virtual threads will be
-included in the list.
-The JDB \f[V]-trackallthreads\f[R] option will cause JDB to
-automatically enable the Debug Agent\[aq]s
-\f[V]includevirtualthreads\f[R] option when JDB launches an application
-to debug.
-However, keep in mind that the Debug Agent may not know about any
-virtual threads that were created before JDB attached to the debugged
-application.
diff --git a/src/jdk.jdi/share/man/jdb.md b/src/jdk.jdi/share/man/jdb.md
new file mode 100644
index 00000000000..e163cbf5e23
--- /dev/null
+++ b/src/jdk.jdi/share/man/jdb.md
@@ -0,0 +1,237 @@
+---
+# Copyright (c) 1995, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JDB(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jdb - find and fix bugs in Java platform programs
+
+## Synopsis
+
+`jdb` \[*options*\] \[*classname*\] \[*arguments*\]
+
+*options*
+:   This represents the `jdb` command-line options. See [Options for the jdb
+    command].
+
+*classname*
+:   This represents the name of the main class to debug.
+
+*arguments*
+:   This represents the arguments that are passed to the `main()` method of the
+    class.
+
+## Description
+
+The Java Debugger (JDB) is a simple command-line debugger for Java classes. The
+`jdb` command and its options call the JDB. The `jdb` command demonstrates the
+Java Platform Debugger Architecture and provides inspection and debugging of a
+local or remote JVM.
+
+## Start a JDB Session
+
+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 `jdb` command for the `java` command in
+the command line. For example, if your application's main class is `MyClass`,
+then use the following command to debug it under the JDB:
+
+>   `jdb MyClass`
+
+When started this way, the `jdb` command calls a second JVM with the specified
+parameters, loads the specified class, and stops the JVM before executing that
+class's first instruction.
+
+Another way to use the `jdb` command is by attaching it to a JVM that's already
+running. Syntax for starting a JVM to which the `jdb` 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.
+
+>   `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass`
+
+You can then attach the `jdb` command to the JVM with the following command:
+
+>   `jdb -attach 8000`
+
+8000 is the address of the running JVM.
+
+The `MyClass` argument isn't specified in the `jdb` command line in this case
+because the `jdb` command is connecting to an existing JVM instead of launching
+a new JVM.
+
+There are many other ways to connect the debugger to a JVM, and all of them are
+supported by the `jdb` command. The Java Platform Debugger Architecture has
+additional documentation on these connection options.
+
+## Breakpoints
+
+Breakpoints can be set in the JDB at line numbers or at the first instruction
+of a method, for example:
+
+-   The command `stop at MyClass:22` sets a breakpoint at the first instruction
+    for line 22 of the source file containing `MyClass`.
+
+-   The command `stop in java.lang.String.length` sets a breakpoint at the
+    beginning of the method `java.lang.String.length`.
+
+-   The command `stop in MyClass.<clinit>` uses `<clinit>` to identify the
+    static initialization code for `MyClass`.
+
+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,
+`MyClass.myMethod(int,java.lang.String)` or `MyClass.myMethod()`.
+
+The `clear` command removes breakpoints using the following syntax:
+`clear MyClass:45`. Using the `clear` or `stop` command with no argument
+displays a list of all breakpoints currently set. The `cont` command continues
+execution.
+
+## Stepping
+
+The `step` command advances execution to the next line whether it's in the
+current stack frame or a called method. The `next` command advances execution
+to the next line in the current stack frame.
+
+## Exceptions
+
+When an exception occurs for which there isn't a `catch` statement anywhere in
+the throwing thread'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 `jdb` command to diagnose the cause
+of the exception.
+
+Use the `catch` command to cause the debugged application to stop at other
+thrown exceptions, for example: `catch java.io.FileNotFoundException` or
+`catch` `mypackage.BigTroubleException`. Any exception that's an instance of
+the specified class or subclass stops the application at the point where the
+exception is thrown.
+
+The `ignore` command negates the effect of an earlier `catch` command. The
+`ignore` command doesn't cause the debugged JVM to ignore specific exceptions,
+but only to ignore the debugger.
+
+## Options for the jdb command
+
+When you use the `jdb` command instead of the `java` command on the command
+line, the `jdb` command accepts many of the same options as the `java`
+command.
+
+The following options are accepted by the `jdb` command:
+
+`-help`
+:   Displays a help message.
+
+`-sourcepath` *dir1*`:`*dir2*`:`...
+:   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 (`.`).
+
+`-attach` *address*
+:   Attaches the debugger to a running JVM with the default connection
+    mechanism.
+
+`-listen` *address*
+:   Waits for a running JVM to connect to the specified address with a standard
+    connector.
+
+`-listenany`
+:   Waits for a running JVM to connect at any available address using a
+    standard connector.
+
+`-launch`
+:   Starts the debugged application immediately upon startup of the `jdb`
+    command. The `-launch` option removes the need for the `run` 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 `cont` command to continue execution.
+
+`-listconnectors`
+:   Lists the connectors available in this JVM.
+
+`-connect` *connector-name*`:`*name1*`=`*value1*....
+:   Connects to the target JVM with the named connector and listed argument
+    values.
+
+`-dbgtrace` \[*flags*\]
+:   Prints information for debugging the `jdb` command.
+
+`-tclient`
+:   Runs the application in the Java HotSpot VM client.
+
+`-trackallthreads`
+:   Track all threads as they are created, including virtual threads.
+    See [Working With Virtual Threads](#working-with-virtual-threads) below.
+
+`-tserver`
+:   Runs the application in the Java HotSpot VM server.
+
+`-J`*option*
+:   Passes *option* to the JDB JVM, where option is one of the options described on
+    the reference page for the Java application launcher. For example,
+    `-J-Xms48m` sets the startup memory to 48 MB. See *Overview of Java
+    Options* in [java](java.html).
+
+The following options are forwarded to the debuggee process:
+
+`-R`*option*
+:   Passes *option* to the debuggee JVM, where option is one of the options described on
+    the reference page for the Java application launcher. For example,
+    `-R-Xms48m` sets the startup memory to 48 MB. See *Overview of Java
+    Options* in [java](java.html).
+
+`-v` or `-verbose`\[`:`*class*\|`gc`\|`jni`\]
+:   Turns on the verbose mode.
+
+`-D`*name*`=`*value*
+:   Sets a system property.
+
+`-classpath` *dir*
+:   Lists directories separated by colons in which to look for classes.
+
+`-X` *option*
+:   A nonstandard target JVM option.
+
+Other options are supported to provide alternate mechanisms for connecting the
+debugger to the JVM that it's to debug.
+
+## Working With Virtual Threads
+
+Often virtual theads are created in such large numbers and frequency that they
+can overwhelm a debugger. For this reason by default JDB does not keep track
+of virtual threads as they are created. It will only keep track of virtual
+threads that an event has arrived on, such as a breakpoint event. The
+`-trackallthreads` option can be used to make JDB track all virtual threads
+as they are created.
+
+When JDB first connects, it requests a list of all known threads from the Debug Agent.
+By default the debug agent does not return any virtual threads in this list, once
+again because the list could be so large that it overwhelms the debugger. The
+Debug Agent has an `includevirtualthreads` option that can be enabled to change
+this behavior so all known virtual threads will be included in the list. The
+JDB `-trackallthreads` option will cause JDB to automatically enable the Debug Agent's
+`includevirtualthreads` option when JDB launches an application to debug. However, keep in mind
+that the Debug Agent may not know about any virtual threads that were created
+before JDB attached to the debugged application.
diff --git a/src/jdk.jfr/share/man/jfr.1 b/src/jdk.jfr/share/man/jfr.1
deleted file mode 100644
index 71a487f558e..00000000000
--- a/src/jdk.jfr/share/man/jfr.1
+++ /dev/null
@@ -1,438 +0,0 @@
-.\" Copyright (c) 2019, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JFR" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jfr - print and manipulate Flight Recorder files
-.SH SYNOPSIS
-.PP
-To print the contents of a flight recording to standard out:
-.PP
-\f[V]jfr\f[R] \f[V]print\f[R] [\f[I]options\f[R]] \f[I]file\f[R]
-.PP
-To display aggregated event data on standard out:
-.PP
-\f[V]jfr\f[R] \f[V]view\f[R] [\f[I]options\f[R]] \f[I]file\f[R]
-.PP
-To configure a .jfc settings file:
-.PP
-\f[V]jfr\f[R] \f[V]configure\f[R] [\f[I]options\f[R]]
-.PP
-To print metadata information about flight recording events:
-.PP
-\f[V]jfr\f[R] \f[V]metadata\f[R] [\f[I]file\f[R]]
-.PP
-To view the summary statistics for a flight recording file:
-.PP
-\f[V]jfr\f[R] \f[V]summary\f[R] \f[I]file\f[R]
-.PP
-To remove events from a flight recording file:
-.PP
-\f[V]jfr\f[R] \f[V]scrub\f[R] [\f[I]options\f[R]] \f[I]file\f[R]
-.PP
-To assemble chunk files into a flight recording file:
-.PP
-\f[V]jfr\f[R] \f[V]assemble\f[R] \f[I]repository\f[R] \f[I]file\f[R]
-.PP
-To disassemble a flight recording file into chunk files:
-.PP
-\f[V]jfr\f[R] \f[V]disassmble\f[R] [\f[I]options\f[R]] \f[I]file\f[R]
-.TP
-\f[I]options\f[R]
-Optional: Specifies command-line options separated by spaces.
-See the individual subcomponent sections for descriptions of the
-available options.
-.TP
-\f[I]file\f[R]
-Specifies the name of the target flight recording file (\f[V].jfr\f[R]).
-.TP
-\f[I]repository\f[R]
-Specifies the location of the chunk files which are to be assembled into
-a flight recording.
-.SH DESCRIPTION
-.PP
-The \f[V]jfr\f[R] command provides a tool for interacting with flight
-recorder files (\f[V].jfr\f[R]).
-The main function is to filter, summarize and output flight recording
-files into human readable format.
-There is also support for scrubbing, merging and splitting recording
-files.
-.PP
-Flight recording files are created and saved as binary formatted files.
-Having a tool that can extract the contents from a flight recording and
-manipulate the contents and translate them into human readable format
-helps developers to debug performance issues with Java applications.
-.SS Subcommands
-.PP
-The \f[V]jfr\f[R] command has several subcommands:
-.IP \[bu] 2
-\f[V]print\f[R]
-.IP \[bu] 2
-\f[V]view\f[R]
-.IP \[bu] 2
-\f[V]configure\f[R]
-.IP \[bu] 2
-\f[V]metadata\f[R]
-.IP \[bu] 2
-\f[V]summary\f[R]
-.IP \[bu] 2
-\f[V]scrub\f[R]
-.IP \[bu] 2
-\f[V]assemble\f[R]
-.IP \[bu] 2
-\f[V]disassemble\f[R]
-.SS \f[V]jfr print\f[R] subcommand
-.PP
-Use \f[V]jfr print\f[R] to print the contents of a flight recording file
-to standard out.
-.PP
-The syntax is:
-.PP
-\f[V]jfr print\f[R] [\f[V]--xml\f[R]|\f[V]--json\f[R]]
-[\f[V]--categories\f[R] <\f[I]filters\f[R]>] [\f[V]--events\f[R]
-<\f[I]filters\f[R]>] [\f[V]--stack-depth\f[R] <\f[I]depth\f[R]>]
-<\f[I]file\f[R]>
-.PP
-where:
-.TP
-\f[V]--xml\f[R]
-Print the recording in XML format.
-.TP
-\f[V]--json\f[R]
-Print the recording in JSON format.
-.TP
-\f[V]--categories\f[R] <\f[I]filters\f[R]>
-Select events matching a category name.
-The filter is a comma-separated list of names, simple and/or qualified,
-and/or quoted glob patterns.
-.TP
-\f[V]--events\f[R] <\f[I]filters\f[R]>
-Select events matching an event name.
-The filter is a comma-separated list of names, simple and/or qualified,
-and/or quoted glob patterns.
-.TP
-\f[V]--stack-depth\f[R] <\f[I]depth\f[R]>
-Number of frames in stack traces, by default 5.
-.TP
-<\f[I]file\f[R]>
-Location of the recording file (\f[V].jfr\f[R])
-.PP
-The default format for printing the contents of the flight recording
-file is human readable form unless either \f[V]xml\f[R] or
-\f[V]json\f[R] is specified.
-These options provide machine-readable output that can be further parsed
-or processed by user created scripts.
-.PP
-Use \f[V]jfr --help print\f[R] to see example usage of filters.
-.PP
-To reduce the amount of data displayed, it is possible to filter out
-events or categories of events.
-The filter operates on the symbolic name of an event, set by using the
-\f[V]\[at]Name\f[R] annotation, or the category name, set by using the
-\f[V]\[at]Category\f[R] annotation.
-If multiple filters are used, events from both filters will be included.
-If no filter is used, all the events will be printed.
-If a combination of a category filter and event filter is used, the
-selected events will be the union of the two filters.
-.PP
-For example, to show all GC events and the CPULoad event, the following
-command could be used:
-.PP
-\f[V]jfr print --categories GC --events CPULoad recording.jfr\f[R]
-.PP
-Event values are formatted according to the content types that are being
-used.
-For example, a field with the \f[V]jdk.jfr.Percentage\f[R] annotation
-that has the value 0.52 is formatted as 52%.
-.PP
-Stack traces are by default truncated to 5 frames, but the number can be
-increased/decreased using the \f[V]--stack-depth\f[R] command-line
-option.
-.SS \f[V]jfr view\f[R] subcommand
-.PP
-Use \f[V]jfr view\f[R] to aggregate and display event data on standard
-out.
-.PP
-The syntax is:
-.PP
-\f[V]jfr view\f[R] [\f[V]--verbose\f[R]] [\f[V]--width\f[R]
-<\f[I]integer\f[R]>] [\f[V]--truncate\f[R] <\f[I]mode\f[R]>]
-[\f[V]--cell-height\f[R] <\f[I]integer\f[R]>] <\f[I]view\f[R]>
-<\f[I]file\f[R]>
-.PP
-where:
-.TP
-\f[V]--verbose\f[R]
-Displays the query that makes up the view.
-.TP
-\f[V]--width\f[R] <\f[I]integer\f[R]>
-The width of the view in characters.
-Default value depends on the view.
-.TP
-\f[V]--truncate\f[R] <\f[I]mode\f[R]>
-How to truncate content that exceeds space in a table cell.
-Mode can be \[aq]beginning\[aq] or \[aq]end\[aq].
-Default value is \[aq]end\[aq].
-.TP
-\f[V]--cell-height\f[R] <\f[I]integer\f[R]>
-Maximum number of rows in a table cell.
-Default value depends on the view.
-.TP
-<\f[I]view\f[R]>
-Name of the view or event type to display.
-Use \f[V]jfr --help view\f[R] to see a list of available views.
-.TP
-<\f[I]file\f[R]>
-Location of the recording file (.jfr)
-.PP
-The <\f[I]view\f[R]> parameter can be an event type name.
-Use the \f[V]jfr view types <file>\f[R] to see a list.
-To display all views, use \f[V]jfr view all-views <file>\f[R].
-To display all events, use \f[V]jfr view all-events <file>\f[R].
-.SS \f[V]jfr configure\f[R] subcommand
-.PP
-Use \f[V]jfr configure\f[R] to configure a .jfc settings file.
-.PP
-The syntax is:
-.PP
-\f[V]jfr configure\f[R] [--interactive] [--verbose] [--input ] [--output
-] [option=value]* [event-setting=value]*
-.TP
-\f[V]--interactive\f[R]
-Interactive mode where the configuration is determined by a set of
-questions.
-.TP
-\f[V]--verbose\f[R]
-Displays the modified settings.
-.TP
-\f[V]--input\f[R] <\f[I]files\f[R]>
-A comma-separated list of .jfc files from which the new configuration is
-based.
-If no file is specified, the default file in the JDK is used
-(default.jfc).
-If \[aq]none\[aq] is specified, the new configuration starts empty.
-.TP
-\f[V]--output\f[R] <\f[I]file\f[R]>
-The filename of the generated output file.
-If not specified, the filename custom.jfc will be used.
-.TP
-\f[I]option=value\f[R]
-The option value to modify.
-To see available options, use \f[V]jfr help configure\f[R]
-.TP
-\f[I]event-setting=value\f[R]
-The event setting value to modify.
-Use the form:
-<\f[I]event-name\f[R]>#<\f[I]setting-name\f[R]>=<\f[I]value\f[R]> To add
-a new event setting, prefix the event name with \[aq]+\[aq].
-.PP
-The whitespace delimiter can be omitted for timespan values, i.e.
-20ms.
-For more information about the settings syntax, see Javadoc of the
-jdk.jfr package.
-.SS \f[V]jfr metadata\f[R] subcommand
-.PP
-Use \f[V]jfr metadata\f[R] to display information about events, such as
-event names, categories and field layout within a flight recording file.
-.PP
-The syntax is:
-.PP
-\f[V]jfr metadata\f[R] [--categories ] [--events ] []
-.TP
-\f[V]--categories\f[R] <\f[I]filter\f[R]>
-Select events matching a category name.
-The filter is a comma-separated list of names, simple and/or qualified,
-and/or quoted glob patterns.
-.TP
-\f[V]--events\f[R] <\f[I]filter\f[R]>
-Select events matching an event name.
-The filter is a comma-separated list of names, simple and/or qualified,
-and/or quoted glob patterns.
-.TP
-<\f[I]file\f[R]>
-Location of the recording file (.jfr)
-.PP
-If the parameter is omitted, metadata from the JDK where the
-\[aq]jfr\[aq] tool is located will be used.
-.SS \f[V]jfr summary\f[R] subcommand
-.PP
-Use \f[V]jfr summary\f[R] to print statistics for a recording.
-For example, a summary can illustrate the number of recorded events and
-how much disk space they used.
-This is useful for troubleshooting and understanding the impact of event
-settings.
-.PP
-The syntax is:
-.PP
-\f[V]jfr summary\f[R] <\f[I]file\f[R]>
-.PP
-where:
-.TP
-<\f[I]file\f[R]>
-Location of the flight recording file (\f[V].jfr\f[R])
-.SS \f[V]jfr scrub\f[R] subcommand
-.PP
-Use \f[V]jfr scrub\f[R] to remove sensitive contents from a file or to
-reduce its size.
-.PP
-The syntax is:
-.PP
-\f[V]jfr scrub\f[R] [--include-events <\f[I]filter\f[R]>]
-[--exclude-events <\f[I]filter\f[R]>] [--include-categories
-<\f[I]filter\f[R]>] [--exclude-categories <\f[I]filter\f[R]>]
-[--include-threads <\f[I]filter\f[R]>] [--exclude-threads
-<\f[I]filter\f[R]>] <\f[I]input-file\f[R]> [<\f[I]output-file\f[R]>]
-.TP
-\f[V]--include-events\f[R] <\f[I]filter\f[R]>
-Select events matching an event name.
-.TP
-\f[V]--exclude-events\f[R] <\f[I]filter\f[R]>
-Exclude events matching an event name.
-.TP
-\f[V]--include-categories\f[R] <\f[I]filter\f[R]>
-Select events matching a category name.
-.TP
-\f[V]--exclude-categories\f[R] <\f[I]filter\f[R]>
-Exclude events matching a category name.
-.TP
-\f[V]--include-threads\f[R] <\f[I]filter\f[R]>
-Select events matching a thread name.
-.TP
-\f[V]--exclude-threads\f[R] <\f[I]filter\f[R]>
-Exclude events matching a thread name.
-.TP
-<\f[I]input-file\f[R]>
-The input file to read events from.
-.TP
-<\f[I]output-file\f[R]>
-The output file to write filter events to.
-If no file is specified, it will be written to the same path as the
-input file, but with \[dq]-scrubbed\[dq] appended to the filename.
-.PP
-The filter is a comma-separated list of names, simple and/or qualified,
-and/or quoted glob patterns.
-If multiple filters are used, they are applied in the specified order.
-.SS \f[V]jfr assemble\f[R] subcommand
-.PP
-Use jfr \f[V]assemble\f[R] to assemble chunk files into a recording
-file.
-.PP
-The syntax is:
-.PP
-\f[V]jfr assemble\f[R] <\f[I]repository\f[R]> <\f[I]file\f[R]>
-.PP
-where:
-.TP
-<\f[I]repository\f[R]>
-Directory where the repository containing chunk files is located.
-.TP
-<\f[I]file\f[R]>
-Location of the flight recording file (\f[V].jfr\f[R]).
-.PP
-Flight recording information is written in chunks.
-A chunk contains all of the information necessary for parsing.
-A chunk typically contains events useful for troubleshooting.
-If a JVM should crash, these chunks can be recovered and used to create
-a flight recording file using this \f[V]jfr assemble\f[R] command.
-These chunk files are concatenated in chronological order and chunk
-files that are not finished (.part) are excluded.
-.SS \f[V]jfr disassemble\f[R] subcommand
-.PP
-Use \f[V]jfr disassemble\f[R] to decompose a flight recording file into
-its chunk file pieces.
-.PP
-The syntax is:
-.PP
-\f[V]jfr disassemble\f[R] [\f[V]--max-chunks\f[R] <\f[I]chunks\f[R]>]
-[\f[V]--output\f[R] <\f[I]directory\f[R]>] <\f[I]file\f[R]>
-.PP
-where:
-.TP
-\f[V]--output\f[R] <\f[I]directory\f[R]>
-The location to write the disassembled file, by default the current
-directory
-.TP
-\f[V]--max-chunks\f[R] <\f[I]chunks\f[R]>
-Maximum number of chunks per file, by default 5.
-The chunk size varies, but is typically around 15 MB.
-.TP
-\f[V]--max-size\f[R] <\f[I]size\f[R]>
-Maximum number of bytes per file.
-.TP
-<\f[I]file\f[R]>
-Location of the flight recording file (\f[V].jfr\f[R])
-.PP
-This function can be useful for repairing a broken file by removing the
-faulty chunk.
-It can also be used to reduce the size of a file that is too large to
-transfer.
-The resulting chunk files are named \f[V]myfile_1.jfr\f[R],
-\f[V]myfile_2.jfr\f[R], etc.
-If needed, the resulting file names will be padded with zeros to
-preserve chronological order.
-For example, the chunk file name is \f[V]myfile_001.jfr\f[R] if the
-recording consists of more than 100 chunks.
-.SS jfr version and help subcommands
-.PP
-Use \f[V]jfr --version\f[R] or \f[V]jfr version\f[R] to view the version
-string information for this jfr command.
-.PP
-To get help on any of the jfr subcommands, use:
-.PP
-\f[V]jfr <--help|help>\f[R] [\f[I]subcommand\f[R]]
-.PP
-where:
-.PP
-[\f[I]subcommand\f[R]] is any of:
-.IP \[bu] 2
-\f[V]print\f[R]
-.IP \[bu] 2
-\f[V]view\f[R]
-.IP \[bu] 2
-\f[V]configure\f[R]
-.IP \[bu] 2
-\f[V]metadata\f[R]
-.IP \[bu] 2
-\f[V]summary\f[R]
-.IP \[bu] 2
-\f[V]scrub\f[R]
-.IP \[bu] 2
-\f[V]assemble\f[R]
-.IP \[bu] 2
-\f[V]disassemble\f[R]
diff --git a/src/jdk.jfr/share/man/jfr.md b/src/jdk.jfr/share/man/jfr.md
new file mode 100644
index 00000000000..f942b97dd99
--- /dev/null
+++ b/src/jdk.jfr/share/man/jfr.md
@@ -0,0 +1,399 @@
+---
+# Copyright (c) 2019, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JFR(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jfr - print and manipulate Flight Recorder files
+
+## Synopsis
+
+To print the contents of a flight recording to standard out:
+
+`jfr` `print` \[*options*\] *file*
+
+To display aggregated event data on standard out:
+
+`jfr` `view` \[*options*\] *file*
+
+To configure a .jfc settings file:
+
+`jfr` `configure` \[*options*\]
+
+To print metadata information about flight recording events:
+
+`jfr` `metadata` \[*file*\]
+
+To view the summary statistics for a flight recording file:
+
+`jfr` `summary` *file*
+
+To remove events from  a flight recording file:
+
+`jfr` `scrub` \[*options*\] *file*
+
+To assemble chunk files into a flight recording file:
+
+`jfr` `assemble` *repository* *file*
+
+To disassemble a flight recording file into chunk files:
+
+`jfr` `disassmble` \[*options*\] *file*
+
+*options*
+:   Optional: Specifies command-line options separated by spaces. See the
+individual subcomponent sections for descriptions of the available options.
+
+*file*
+:   Specifies the name of the target flight recording file (`.jfr`).
+
+*repository*
+:   Specifies the location of the chunk files which are to be assembled into
+a flight recording.
+
+## Description
+
+The `jfr` command provides a tool for interacting with flight recorder files
+(`.jfr`). The main function is to filter, summarize and output flight
+recording files into human readable format. There is also support for scrubbing,
+merging and splitting recording files.
+
+Flight recording files are created and saved as binary formatted files. Having
+a tool that can extract the contents from a flight recording and manipulate the
+contents and translate them into human readable format helps developers to debug
+performance issues with Java applications.
+
+### Subcommands
+
+The `jfr` command has several subcommands:
+
+- `print`
+- `view`
+- `configure`
+- `metadata`
+- `summary`
+- `scrub`
+- `assemble`
+- `disassemble`
+
+#### `jfr print` subcommand
+
+Use `jfr print` to print the contents of a flight recording file to standard out.
+
+The syntax is:
+
+`jfr print` \[`--xml`|`--json`\]
+           \[`--categories` <*filters*>\]
+           \[`--events` <*filters*>\]
+           \[`--stack-depth` <*depth*>\]
+           <*file*>
+
+where:
+
+<a id="print-option-xml">`--xml`</a>
+: Print the recording in XML format.
+
+<a id="print-option-json">`--json`</a>
+: Print the recording in JSON format.
+
+<a id="print-option-categories">`--categories` <*filters*></a>
+: Select events matching a category name.
+The filter is a comma-separated list of names,
+simple and/or qualified, and/or quoted glob patterns.
+
+<a id="print-option-events">`--events` <*filters*></a>
+: Select events matching an event name.
+The filter is a comma-separated list of names,
+simple and/or qualified, and/or quoted glob patterns.
+
+<a id="print-option-stack-depth">`--stack-depth` <*depth*></a>
+: Number of frames in stack traces, by default 5.
+
+<a id="print-option-file"><*file*></a>
+: Location of the recording file (`.jfr`)
+
+The default format for printing the contents of the flight recording file is human
+readable form unless either `xml` or `json` is specified. These options provide
+machine-readable output that can be further parsed or processed by user created scripts.
+
+Use `jfr --help print` to see example usage of filters.
+
+To reduce the amount of data displayed, it is possible to filter out events or
+categories of events. The filter operates on the symbolic name of an event,
+set by using the `@Name` annotation, or the category name, set by using
+the `@Category` annotation. If multiple filters are used, events from both
+filters will be included. If no filter is used, all the events will be printed.
+If a combination of a category filter and event filter is used, the selected events
+will be the union of the two filters.
+
+For example, to show all GC events and the CPULoad event, the following command could be used:
+
+`jfr print --categories GC --events CPULoad recording.jfr`
+
+Event values are formatted according to the content types that are being used.
+For example, a field with the `jdk.jfr.Percentage` annotation that has the value 0.52
+is formatted as 52%.
+
+Stack traces are by default truncated to 5 frames, but the number can be
+increased/decreased using the `--stack-depth` command-line option.
+
+#### `jfr view` subcommand
+
+Use `jfr view` to aggregate and display event data on standard out.
+
+The syntax is:
+
+ `jfr view` \[`--verbose`\]
+           \[`--width` <*integer*>\]
+           \[`--truncate` <*mode*>\]
+           \[`--cell-height` <*integer*>\]
+            <*view*>
+            <*file*>
+
+where:
+
+<a id="view-option-verbose">`--verbose`</a>
+: Displays the query that makes up the view.
+
+<a id="view-option-width">`--width` <*integer*></a>
+: The width of the view in characters. Default value depends on the view.
+
+<a id="view-option-truncate">`--truncate` <*mode*></a>
+: How to truncate content that exceeds space in a table cell.
+Mode can be 'beginning' or 'end'. Default value is 'end'.
+
+<a id="view-option-cell-height">`--cell-height` <*integer*></a>
+: Maximum number of rows in a table cell. Default value depends on the view.
+
+<a id="view-option-view"><*view*></a>
+: Name of the view or event type to display. Use `jfr --help view` to see a
+list of available views.
+
+<a id="view-option-file"><*file*></a>
+: Location of the recording file (.jfr)
+
+The <*view*> parameter can be an event type name. Use the `jfr view types <file>`
+to see a list. To display all views, use `jfr view all-views <file>`. To display
+all events, use `jfr view all-events <file>`.
+
+#### `jfr configure` subcommand
+
+Use `jfr configure` to configure a .jfc settings file.
+
+The syntax is:
+
+ `jfr configure` \[--interactive\] \[--verbose\]
+               \[--input <files>\] [--output <file>\]
+               \[option=value\]* \[event-setting=value\]*
+
+<a id="configure-option-interactive">`--interactive`</a>
+: Interactive mode where the configuration is determined by a set of questions.
+
+<a id="configure-option-verbose">`--verbose`</a>
+: Displays the modified settings.
+
+<a id="configure-option-input">`--input` <*files*></a>
+: A comma-separated list of .jfc files from which the new configuration is
+based. If no file is specified, the default file in the JDK is used
+(default.jfc). If 'none' is specified, the new configuration starts empty.
+
+<a id="configure-option-output">`--output` <*file*></a>
+: The filename of the generated output file. If not specified, the filename
+custom.jfc will be used.
+
+<a id="configure-option-value">*option=value*</a>
+: The option value to modify. To see available options,
+use `jfr help configure`
+
+<a id="configure-option-event-setting">*event-setting=value*</a>
+: The event setting value to modify. Use the form:
+  <*event-name*>#<*setting-name*>=<*value*>
+To add a new event setting, prefix the event name with '+'.
+
+The whitespace delimiter can be omitted for timespan values, i.e. 20ms. For
+more information about the settings syntax, see Javadoc of the jdk.jfr package.
+
+#### `jfr metadata` subcommand
+
+Use `jfr metadata` to display information about events, such as event
+names, categories and field layout within a flight recording file.
+
+The syntax is:
+
+`jfr metadata` \[--categories <filter>\]
+              \[--events <filter>\]
+              \[<file>\]
+
+<a id="metadata-option-categories">`--categories` <*filter*></a>
+: Select events matching a category name. The filter is a comma-separated
+list of names, simple and/or qualified, and/or quoted glob patterns.
+
+<a id="metadata-option-events">`--events` <*filter*></a>
+: Select events matching an event name. The filter is a comma-separated
+list of names, simple and/or qualified, and/or quoted glob patterns.
+
+<a id="metadata-option-file"><*file*></a>
+: Location of the recording file (.jfr)
+
+If the <file> parameter is omitted, metadata from the JDK where
+the 'jfr' tool is located will be used.
+
+#### `jfr summary` subcommand
+
+Use `jfr summary` to print statistics for a recording. For example, a summary can
+illustrate the number of recorded events and how much disk space they used. This
+is useful for troubleshooting and understanding the impact of event settings.
+
+The syntax is:
+
+`jfr summary` <*file*>
+
+where:
+
+<a id="summary-option-file"><*file*></a>
+: Location of the flight recording file (`.jfr`)
+
+#### `jfr scrub` subcommand
+
+Use `jfr scrub` to remove sensitive contents from a file or to reduce its size.
+
+The syntax is:
+
+`jfr scrub` \[--include-events <*filter*>\]
+           \[--exclude-events <*filter*>\]
+           \[--include-categories <*filter*>\]
+           \[--exclude-categories <*filter*>\]
+           \[--include-threads <*filter*>\]
+           \[--exclude-threads <*filter*>\]
+           <*input-file*>
+           \[<*output-file*>\]
+
+<a id="scrub-option-include-events">`--include-events` <*filter*></a>
+: Select events matching an event name.
+
+<a id="scrub-option-exclude-events">`--exclude-events` <*filter*></a>
+: Exclude events matching an event name.
+
+<a id="scrub-option-include-categories">`--include-categories` <*filter*></a>
+: Select events matching a category name.
+
+<a id="scrub-option-exclude-categories">`--exclude-categories` <*filter*></a>
+: Exclude events matching a category name.
+
+<a id="scrub-option-include-threads">`--include-threads` <*filter*></a>
+: Select events matching a thread name.
+
+<a id="scrub-option-exclude-threads">`--exclude-threads` <*filter*></a>
+: Exclude events matching a thread name.
+
+<a id="scrub-option-input-file"><*input-file*></a>
+: The input file to read events from.
+
+<a id="scrub-option-output-file"><*output-file*></a>
+: The output file to write filter events to. If no file is specified,
+it will be written to the same  path as the input file, but with
+"-scrubbed" appended to the filename.
+
+The filter is a comma-separated list of names, simple and/or qualified,
+and/or quoted glob patterns. If multiple filters are used, they
+are applied in the specified order.
+
+#### `jfr assemble` subcommand
+
+Use jfr `assemble` to assemble chunk files into a recording file.
+
+The syntax is:
+
+`jfr assemble` <*repository*>
+               <*file*>
+
+where:
+
+<a id="assemble-option-repository"><*repository*></a>
+: Directory where the repository containing chunk files is located.
+
+<a id="assemble-option-file"><*file*></a>
+: Location of the flight recording file (`.jfr`).
+
+Flight recording information is written in chunks. A chunk contains all of the information
+necessary for parsing. A chunk typically contains events useful for troubleshooting.
+If a JVM should crash, these chunks can be recovered and used to create a flight
+recording file using this `jfr assemble` command. These chunk files are concatenated in
+chronological order and chunk files that are not finished (.part) are excluded.
+
+#### `jfr disassemble` subcommand
+
+Use `jfr disassemble` to decompose a flight recording file into its chunk file pieces.
+
+The syntax is:
+
+`jfr disassemble` \[`--max-chunks` <*chunks*>\]
+                  \[`--output` <*directory*>\]
+                  <*file*>
+
+where:
+
+<a id="disassemble-option-output">`--output` <*directory*></a>
+: The location to write the disassembled file,
+by default the current directory
+
+<a id="disassemble-option-max-chunks">`--max-chunks` <*chunks*></a>
+: Maximum number of chunks per file, by default 5.
+The chunk size varies, but is typically around 15 MB.
+
+<a id="disassemble-option-max-size">`--max-size` <*size*></a>
+: Maximum number of bytes per file.
+
+<a id="disassemble-option-file"><*file*></a>
+: Location of the flight recording file (`.jfr`)
+
+This function can be useful for repairing a broken file by removing the faulty chunk.
+It can also be used to reduce the size of a file that is too large to transfer.
+The resulting chunk files are named `myfile_1.jfr`, `myfile_2.jfr`, etc. If needed, the
+resulting file names will be padded with zeros to preserve chronological order. For example,
+the chunk file name is `myfile_001.jfr` if the recording consists of more than 100 chunks.
+
+#### jfr version and help subcommands
+
+Use `jfr --version` or `jfr version` to view the version string information for this jfr command.
+
+To get help on any of the jfr subcommands, use:
+
+`jfr <--help|help>` \[*subcommand*\]
+
+where:
+
+\[*subcommand*\] is any of:
+
+- `print`
+- `view`
+- `configure`
+- `metadata`
+- `summary`
+- `scrub`
+- `assemble`
+- `disassemble`
diff --git a/src/jdk.jlink/share/man/jlink.1 b/src/jdk.jlink/share/man/jlink.1
deleted file mode 100644
index 5cadc153a37..00000000000
--- a/src/jdk.jlink/share/man/jlink.1
+++ /dev/null
@@ -1,409 +0,0 @@
-.\" Copyright (c) 2017, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JLINK" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jlink - assemble and optimize a set of modules and their dependencies
-into a custom runtime image
-.SH SYNOPSIS
-.PP
-\f[V]jlink\f[R] [\f[I]options\f[R]] \f[V]--module-path\f[R]
-\f[I]modulepath\f[R] \f[V]--add-modules\f[R]
-\f[I]module\f[R][,\f[I]module\f[R]...]
-.TP
-\f[I]options\f[R]
-Command-line options separated by spaces.
-See \f[B]jlink Options\f[R].
-.TP
-\f[I]modulepath\f[R]
-The path where the \f[V]jlink\f[R] tool discovers observable modules.
-These modules can be modular JAR files, JMOD files, or exploded modules.
-.TP
-\f[I]module\f[R]
-The names of the modules to add to the runtime image.
-The \f[V]jlink\f[R] tool adds these modules and their transitive
-dependencies.
-.SH DESCRIPTION
-.PP
-The \f[V]jlink\f[R] tool links a set of modules, along with their
-transitive dependences, to create a custom runtime image.
-.PP
-\f[B]Note:\f[R]
-.PP
-Developers are responsible for updating their custom runtime images.
-.SH JLINK OPTIONS
-.TP
-\f[V]--add-modules\f[R] \f[I]mod\f[R][\f[V],\f[R]\f[I]mod\f[R]...]
-Adds the named modules, \f[I]mod\f[R], to the default set of root
-modules.
-The default set of root modules is empty.
-.TP
-\f[V]--bind-services\f[R]
-Link service provider modules and their dependencies.
-.TP
-\f[V]-c ={0|1|2}\f[R] or \f[V]--compress={0|1|2}\f[R]
-Enable compression of resources:
-.RS
-.IP \[bu] 2
-\f[V]0\f[R]: No compression
-.IP \[bu] 2
-\f[V]1\f[R]: Constant string sharing
-.IP \[bu] 2
-\f[V]2\f[R]: ZIP
-.RE
-.TP
-\f[V]--disable-plugin\f[R] \f[I]pluginname\f[R]
-Disables the specified plug-in.
-See \f[B]jlink Plug-ins\f[R] for the list of supported plug-ins.
-.TP
-\f[V]--endian\f[R] {\f[V]little\f[R]|\f[V]big\f[R]}
-Specifies the byte order of the generated image.
-The default value is the format of your system\[aq]s architecture.
-.TP
-\f[V]-h\f[R] or \f[V]--help\f[R]
-Prints the help message.
-.TP
-\f[V]--ignore-signing-information\f[R]
-Suppresses a fatal error when signed modular JARs are linked in the
-runtime image.
-The signature-related files of the signed modular JARs aren\[aq]t copied
-to the runtime image.
-.TP
-\f[V]--launcher\f[R] \f[I]command\f[R]\f[V]=\f[R]\f[I]module\f[R] or \f[V]--launcher\f[R] \f[I]command\f[R]\f[V]=\f[R]\f[I]module\f[R]\f[V]/\f[R]\f[I]main\f[R]
-Specifies the launcher command name for the module or the command name
-for the module and main class (the module and the main class names are
-separated by a slash (\f[V]/\f[R])).
-.TP
-\f[V]--limit-modules\f[R] \f[I]mod\f[R][\f[V],\f[R]\f[I]mod\f[R]...]
-Limits the universe of observable modules to those in the transitive
-closure of the named modules, \f[V]mod\f[R], plus the main module, if
-any, plus any further modules specified in the \f[V]--add-modules\f[R]
-option.
-.TP
-\f[V]--list-plugins\f[R]
-Lists available plug-ins, which you can access through command-line
-options; see \f[B]jlink Plug-ins\f[R].
-.TP
-\f[V]-p\f[R] or \f[V]--module-path\f[R] \f[I]modulepath\f[R]
-Specifies the module path.
-.RS
-.PP
-If this option is not specified, then the default module path is
-\f[V]$JAVA_HOME/jmods\f[R].
-This directory contains the \f[V]java.base\f[R] module and the other
-standard and JDK modules.
-If this option is specified but the \f[V]java.base\f[R] module cannot be
-resolved from it, then the \f[V]jlink\f[R] command appends
-\f[V]$JAVA_HOME/jmods\f[R] to the module path.
-.RE
-.TP
-\f[V]--no-header-files\f[R]
-Excludes header files.
-.TP
-\f[V]--no-man-pages\f[R]
-Excludes man pages.
-.TP
-\f[V]--output\f[R] \f[I]path\f[R]
-Specifies the location of the generated runtime image.
-.TP
-\f[V]--save-opts\f[R] \f[I]filename\f[R]
-Saves \f[V]jlink\f[R] options in the specified file.
-.TP
-\f[V]--suggest-providers\f[R] [\f[I]name\f[R]\f[V],\f[R] ...]
-Suggest providers that implement the given service types from the module
-path.
-.TP
-\f[V]--version\f[R]
-Prints version information.
-.TP
-\f[V]\[at]\f[R]\f[I]filename\f[R]
-Reads options from the specified file.
-.RS
-.PP
-An options file is a text file that contains the options and values that
-you would typically enter in a command prompt.
-Options may appear on one line or on several lines.
-You may not specify environment variables for path names.
-You may comment out lines by prefixing a hash symbol (\f[V]#\f[R]) to
-the beginning of the line.
-.PP
-The following is an example of an options file for the \f[V]jlink\f[R]
-command:
-.IP
-.nf
-\f[CB]
-#Wed Dec 07 00:40:19 EST 2016
---module-path mlib
---add-modules com.greetings
---output greetingsapp
-\f[R]
-.fi
-.RE
-.SH JLINK PLUG-INS
-.PP
-\f[B]Note:\f[R]
-.PP
-Plug-ins not listed in this section aren\[aq]t supported and are subject
-to change.
-.PP
-For plug-in options that require a \f[I]pattern-list\f[R], the value is
-a comma-separated list of elements, with each element using one the
-following forms:
-.IP \[bu] 2
-\f[I]glob-pattern\f[R]
-.IP \[bu] 2
-\f[V]glob:\f[R]\f[I]glob-pattern\f[R]
-.IP \[bu] 2
-\f[V]regex:\f[R]\f[I]regex-pattern\f[R]
-.IP \[bu] 2
-\f[V]\[at]\f[R]\f[I]filename\f[R]
-.RS 2
-.IP \[bu] 2
-\f[I]filename\f[R] is the name of a file that contains patterns to be
-used, one pattern per line.
-.RE
-.PP
-For a complete list of all available plug-ins, run the command
-\f[V]jlink --list-plugins\f[R].
-.SS Plugin \f[V]compress\f[R]
-.TP
-Options
-\f[V]--compress=\f[R]{\f[V]0\f[R]|\f[V]1\f[R]|\f[V]2\f[R]}[\f[V]:filter=\f[R]\f[I]pattern-list\f[R]]
-.TP
-Description
-Compresses all resources in the output image.
-.RS
-.IP \[bu] 2
-Level 0: No compression
-.IP \[bu] 2
-Level 1: Constant string sharing
-.IP \[bu] 2
-Level 2: ZIP
-.PP
-An optional \f[I]pattern-list\f[R] filter can be specified to list the
-pattern of files to include.
-.RE
-.SS Plugin \f[V]include-locales\f[R]
-.TP
-Options
-\f[V]--include-locales=\f[R]\f[I]langtag\f[R][\f[V],\f[R]\f[I]langtag\f[R]]*
-.TP
-Description
-Includes the list of locales where \f[I]langtag\f[R] is a BCP 47
-language tag.
-This option supports locale matching as defined in RFC 4647.
-Ensure that you add the module jdk.localedata when using this option.
-.RS
-.PP
-Example:
-.RS
-.PP
-\f[V]--add-modules jdk.localedata --include-locales=en,ja,*-IN\f[R]
-.RE
-.RE
-.SS Plugin \f[V]order-resources\f[R]
-.TP
-Options
-\f[V]--order-resources=\f[R]\f[I]pattern-list\f[R]
-.TP
-Description
-Orders the specified paths in priority order.
-If \f[V]\[at]\f[R]\f[I]filename\f[R] is specified, then each line in
-\f[I]pattern-list\f[R] must be an exact match for the paths to be
-ordered.
-.RS
-.PP
-Example:
-.RS
-.PP
-\f[V]--order-resources=/module-info.class,\[at]classlist,/java.base/java/lang/\f[R]
-.RE
-.RE
-.SS Plugin \f[V]strip-debug\f[R]
-.TP
-Options
-\f[V]--strip-debug\f[R]
-.TP
-Description
-Strips debug information from the output image.
-.SS Plugin \f[V]generate-cds-archive\f[R]
-.TP
-Options
-\f[V]--generate-cds-archive\f[R]
-.TP
-Description
-Generate CDS archive if the runtime image supports the CDS feature.
-.SH JLINK EXAMPLES
-.PP
-The following command creates a runtime image in the directory
-\f[V]greetingsapp\f[R].
-This command links the module \f[V]com.greetings\f[R], whose module
-definition is contained in the directory \f[V]mlib\f[R].
-.IP
-.nf
-\f[CB]
-jlink --module-path mlib --add-modules com.greetings --output greetingsapp
-\f[R]
-.fi
-.PP
-The following command lists the modules in the runtime image
-\f[V]greetingsapp\f[R]:
-.IP
-.nf
-\f[CB]
-greetingsapp/bin/java --list-modules
-com.greetings
-java.base\[at]11
-java.logging\[at]11
-org.astro\[at]1.0
-\f[R]
-.fi
-.PP
-The following command creates a runtime image in the directory
-compressedrt that\[aq]s stripped of debug symbols, uses compression to
-reduce space, and includes French language locale information:
-.IP
-.nf
-\f[CB]
-jlink --add-modules jdk.localedata --strip-debug --compress=2 --include-locales=fr --output compressedrt
-\f[R]
-.fi
-.PP
-The following example compares the size of the runtime image
-\f[V]compressedrt\f[R] with \f[V]fr_rt\f[R], which isn\[aq]t stripped of
-debug symbols and doesn\[aq]t use compression:
-.IP
-.nf
-\f[CB]
-jlink --add-modules jdk.localedata --include-locales=fr --output fr_rt
-
-du -sh ./compressedrt ./fr_rt
-23M     ./compressedrt
-36M     ./fr_rt
-\f[R]
-.fi
-.PP
-The following example lists the providers that implement
-\f[V]java.security.Provider\f[R]:
-.IP
-.nf
-\f[CB]
-jlink --suggest-providers java.security.Provider
-
-Suggested providers:
-  java.naming provides java.security.Provider used by java.base
-  java.security.jgss provides java.security.Provider used by java.base
-  java.security.sasl provides java.security.Provider used by java.base
-  java.smartcardio provides java.security.Provider used by java.base
-  java.xml.crypto provides java.security.Provider used by java.base
-  jdk.crypto.cryptoki provides java.security.Provider used by java.base
-  jdk.crypto.ec provides java.security.Provider used by java.base
-  jdk.crypto.mscapi provides java.security.Provider used by java.base
-  jdk.security.jgss provides java.security.Provider used by java.base
-\f[R]
-.fi
-.PP
-The following example creates a custom runtime image named
-\f[V]mybuild\f[R] that includes only \f[V]java.naming\f[R] and
-\f[V]jdk.crypto.cryptoki\f[R] and their dependencies but no other
-providers.
-Note that these dependencies must exist in the module path:
-.IP
-.nf
-\f[CB]
-jlink --add-modules java.naming,jdk.crypto.cryptoki --output mybuild
-\f[R]
-.fi
-.PP
-The following command is similar to the one that creates a runtime image
-named \f[V]greetingsapp\f[R], except that it will link the modules
-resolved from root modules with service binding; see the
-\f[B]\f[VB]Configuration.resolveAndBind\f[B]\f[R] method.
-.IP
-.nf
-\f[CB]
-jlink --module-path mlib --add-modules com.greetings --output greetingsapp --bind-services
-\f[R]
-.fi
-.PP
-The following command lists the modules in the runtime image
-greetingsapp created by this command:
-.IP
-.nf
-\f[CB]
-greetingsapp/bin/java --list-modules
-com.greetings
-java.base\[at]11
-java.compiler\[at]11
-java.datatransfer\[at]11
-java.desktop\[at]11
-java.logging\[at]11
-java.management\[at]11
-java.management.rmi\[at]11
-java.naming\[at]11
-java.prefs\[at]11
-java.rmi\[at]11
-java.security.jgss\[at]11
-java.security.sasl\[at]11
-java.smartcardio\[at]11
-java.xml\[at]11
-java.xml.crypto\[at]11
-jdk.accessibility\[at]11
-jdk.charsets\[at]11
-jdk.compiler\[at]11
-jdk.crypto.cryptoki\[at]11
-jdk.crypto.ec\[at]11
-jdk.crypto.mscapi\[at]11
-jdk.internal.opt\[at]11
-jdk.jartool\[at]11
-jdk.javadoc\[at]11
-jdk.jdeps\[at]11
-jdk.jfr\[at]11
-jdk.jlink\[at]11
-jdk.localedata\[at]11
-jdk.management\[at]11
-jdk.management.jfr\[at]11
-jdk.naming.dns\[at]11
-jdk.naming.rmi\[at]11
-jdk.security.auth\[at]11
-jdk.security.jgss\[at]11
-jdk.zipfs\[at]11
-org.astro\[at]1.0
-\f[R]
-.fi
diff --git a/src/jdk.jlink/share/man/jlink.md b/src/jdk.jlink/share/man/jlink.md
new file mode 100644
index 00000000000..8c344a692cb
--- /dev/null
+++ b/src/jdk.jlink/share/man/jlink.md
@@ -0,0 +1,347 @@
+---
+# Copyright (c) 2017, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JLINK(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jlink - assemble and optimize a set of modules and their dependencies into a
+custom runtime image
+
+## Synopsis
+
+`jlink` \[*options*\] `--module-path` *modulepath* `--add-modules` *module*\[,*module*...\]
+
+*options*
+:   Command-line options separated by spaces. See [jlink Options].
+
+*modulepath*
+:   The path where the `jlink` tool discovers observable modules. These modules
+    can be modular JAR files, JMOD files, or exploded modules.
+
+*module*
+:   The names of the modules to add to the runtime image. The `jlink` tool adds
+    these modules and their transitive dependencies.
+
+## Description
+
+The `jlink` tool links a set of modules, along with their transitive
+dependences, to create a custom runtime image.
+
+**Note:**
+
+Developers are responsible for updating their custom runtime images.
+
+## jlink Options
+
+`--add-modules` *mod*\[`,`*mod*...\]
+:   Adds the named modules, *mod*, to the default set of root modules. The
+    default set of root modules is empty.
+
+`--bind-services`
+:   Link service provider modules and their dependencies.
+
+`-c ={0|1|2}` or `--compress={0|1|2}`
+:   Enable compression of resources:
+
+    -   `0`: No compression
+    -   `1`: Constant string sharing
+    -   `2`: ZIP
+
+`--disable-plugin` *pluginname*
+:   Disables the specified plug-in. See [jlink Plug-ins] for the list of
+    supported plug-ins.
+
+`--endian` {`little`\|`big`}
+:   Specifies the byte order of the generated image. The default value is the
+    format of your system's architecture.
+
+`-h` or `--help`
+:   Prints the help message.
+
+`--ignore-signing-information`
+:   Suppresses a fatal error when signed modular JARs are linked in the runtime
+    image. The signature-related files of the signed modular JARs aren't copied
+    to the runtime image.
+
+`--launcher` *command*`=`*module* or `--launcher` *command*`=`*module*`/`*main*
+:   Specifies the launcher command name for the module or the command name for
+    the module and main class (the module and the main class names are
+    separated by a slash (`/`)).
+
+`--limit-modules` *mod*\[`,`*mod*...\]
+:   Limits the universe of observable modules to those in the transitive
+    closure of the named modules, `mod`, plus the main module, if any, plus any
+    further modules specified in the `--add-modules` option.
+
+`--list-plugins`
+:   Lists available plug-ins, which you can access through command-line
+    options; see [jlink Plug-ins].
+
+`-p` or `--module-path` *modulepath*
+:   Specifies the module path.
+
+    If this option is not specified, then the default module path is
+    `$JAVA_HOME/jmods`. This directory contains the `java.base` module and the
+    other standard and JDK modules. If this option is specified but the
+    `java.base` module cannot be resolved from it, then the `jlink` command
+    appends `$JAVA_HOME/jmods` to the module path.
+
+`--no-header-files`
+:   Excludes header files.
+
+`--no-man-pages`
+:   Excludes man pages.
+
+`--output` *path*
+:   Specifies the location of the generated runtime image.
+
+`--save-opts` *filename*
+:   Saves `jlink` options in the specified file.
+
+`--suggest-providers` \[*name*`,` ...\]
+:   Suggest providers that implement the given service types from the module
+    path.
+
+`--version`
+:   Prints version information.
+
+`@`*filename*
+:   Reads options from the specified file.
+
+    An options file is a text file that contains the options and values that
+    you would typically enter in a command prompt. Options may appear on one
+    line or on several lines. You may not specify environment variables for
+    path names. You may comment out lines by prefixing a hash symbol (`#`) to
+    the beginning of the line.
+
+    The following is an example of an options file for the `jlink` command:
+
+    ```
+    #Wed Dec 07 00:40:19 EST 2016
+    --module-path mlib
+    --add-modules com.greetings
+    --output greetingsapp
+    ```
+
+## jlink Plug-ins
+
+**Note:**
+
+Plug-ins not listed in this section aren't supported and are subject to change.
+
+For plug-in options that require a *pattern-list*, the value is a
+comma-separated list of elements, with each element using one the following
+forms:
+
+-   *glob-pattern*
+-   `glob:`*glob-pattern*
+-   `regex:`*regex-pattern*
+-   `@`*filename*
+    -   *filename* is the name of a file that contains patterns to be used, one
+        pattern per line.
+
+For a complete list of all available plug-ins, run the command
+`jlink --list-plugins`.
+
+### Plugin `compress`
+
+Options
+:   `--compress=`{`0`\|`1`\|`2`}\[`:filter=`*pattern-list*\]
+
+Description
+:   Compresses all resources in the output image.
+
+    -   Level 0: No compression
+    -   Level 1: Constant string sharing
+    -   Level 2: ZIP
+
+    An optional *pattern-list* filter can be specified to list the pattern of
+    files to include.
+
+### Plugin `include-locales`
+
+Options
+:   `--include-locales=`*langtag*\[`,`*langtag*\]\*
+
+Description
+:   Includes the list of locales where *langtag* is a BCP 47 language tag.
+    This option supports locale matching as defined in RFC 4647. Ensure that
+    you add the module jdk.localedata when using this option.
+
+    Example:
+
+    >   `--add-modules jdk.localedata --include-locales=en,ja,*-IN`
+
+### Plugin `order-resources`
+
+Options
+:   `--order-resources=`*pattern-list*
+
+Description
+:   Orders the specified paths in priority order. If `@`*filename* is
+    specified, then each line in *pattern-list* must be an exact match for the
+    paths to be ordered.
+
+    Example:
+
+    >   `--order-resources=/module-info.class,@classlist,/java.base/java/lang/`
+
+### Plugin `strip-debug`
+
+Options
+:   `--strip-debug`
+
+Description
+:   Strips debug information from the output image.
+
+### Plugin `generate-cds-archive`
+
+Options
+:   `--generate-cds-archive`
+
+Description
+:   Generate CDS archive if the runtime image supports the CDS feature.
+
+## jlink Examples
+
+The following command creates a runtime image in the directory `greetingsapp`.
+This command links the module `com.greetings`, whose module definition is
+contained in the directory `mlib`.
+
+```
+jlink --module-path mlib --add-modules com.greetings --output greetingsapp
+```
+
+The following command lists the modules in the runtime image `greetingsapp`:
+
+```
+greetingsapp/bin/java --list-modules
+com.greetings
+java.base@11
+java.logging@11
+org.astro@1.0
+```
+
+The following command creates a runtime image in the directory compressedrt
+that's stripped of debug symbols, uses compression to reduce space, and
+includes French language locale information:
+
+```
+jlink --add-modules jdk.localedata --strip-debug --compress=2 --include-locales=fr --output compressedrt
+```
+
+The following example compares the size of the runtime image `compressedrt`
+with `fr_rt`, which isn't stripped of debug symbols and doesn't use
+compression:
+
+```
+jlink --add-modules jdk.localedata --include-locales=fr --output fr_rt
+
+du -sh ./compressedrt ./fr_rt
+23M     ./compressedrt
+36M     ./fr_rt
+```
+
+The following example lists the providers that implement
+`java.security.Provider`:
+
+```
+jlink --suggest-providers java.security.Provider
+
+Suggested providers:
+  java.naming provides java.security.Provider used by java.base
+  java.security.jgss provides java.security.Provider used by java.base
+  java.security.sasl provides java.security.Provider used by java.base
+  java.smartcardio provides java.security.Provider used by java.base
+  java.xml.crypto provides java.security.Provider used by java.base
+  jdk.crypto.cryptoki provides java.security.Provider used by java.base
+  jdk.crypto.ec provides java.security.Provider used by java.base
+  jdk.crypto.mscapi provides java.security.Provider used by java.base
+  jdk.security.jgss provides java.security.Provider used by java.base
+```
+
+The following example creates a custom runtime image named `mybuild` that
+includes only `java.naming` and `jdk.crypto.cryptoki` and their dependencies but no
+other providers. Note that these dependencies must exist in the module path:
+
+```
+jlink --add-modules java.naming,jdk.crypto.cryptoki --output mybuild
+```
+
+The following command is similar to the one that creates a runtime image named
+`greetingsapp`, except that it will link the modules resolved from root modules
+with service binding; see the [`Configuration.resolveAndBind`](
+../../api/java.base/java/lang/module/Configuration.html#resolveAndBind(java.lang.module.ModuleFinder,java.util.List,java.lang.module.ModuleFinder,java.util.Collection))
+method.
+
+```
+jlink --module-path mlib --add-modules com.greetings --output greetingsapp --bind-services
+```
+
+The following command lists the modules in the runtime image greetingsapp
+created by this command:
+
+```
+greetingsapp/bin/java --list-modules
+com.greetings
+java.base@11
+java.compiler@11
+java.datatransfer@11
+java.desktop@11
+java.logging@11
+java.management@11
+java.management.rmi@11
+java.naming@11
+java.prefs@11
+java.rmi@11
+java.security.jgss@11
+java.security.sasl@11
+java.smartcardio@11
+java.xml@11
+java.xml.crypto@11
+jdk.accessibility@11
+jdk.charsets@11
+jdk.compiler@11
+jdk.crypto.cryptoki@11
+jdk.crypto.ec@11
+jdk.crypto.mscapi@11
+jdk.internal.opt@11
+jdk.jartool@11
+jdk.javadoc@11
+jdk.jdeps@11
+jdk.jfr@11
+jdk.jlink@11
+jdk.localedata@11
+jdk.management@11
+jdk.management.jfr@11
+jdk.naming.dns@11
+jdk.naming.rmi@11
+jdk.security.auth@11
+jdk.security.jgss@11
+jdk.zipfs@11
+org.astro@1.0
+```
diff --git a/src/jdk.jlink/share/man/jmod.1 b/src/jdk.jlink/share/man/jmod.1
deleted file mode 100644
index 4475505e524..00000000000
--- a/src/jdk.jlink/share/man/jmod.1
+++ /dev/null
@@ -1,423 +0,0 @@
-.\" Copyright (c) 2017, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JMOD" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jmod - create JMOD files and list the content of existing JMOD files
-.SH SYNOPSIS
-.PP
-\f[V]jmod\f[R]
-(\f[V]create\f[R]|\f[V]extract\f[R]|\f[V]list\f[R]|\f[V]describe\f[R]|\f[V]hash\f[R])
-[\f[I]options\f[R]] \f[I]jmod-file\f[R]
-.PP
-Includes the following:
-.PP
-\f[B]Main operation modes\f[R]
-.TP
-\f[V]create\f[R]
-Creates a new JMOD archive file.
-.TP
-\f[V]extract\f[R]
-Extracts all the files from the JMOD archive file.
-.TP
-\f[V]list\f[R]
-Prints the names of all the entries.
-.TP
-\f[V]describe\f[R]
-Prints the module details.
-.TP
-\f[V]hash\f[R]
-Determines leaf modules and records the hashes of the dependencies that
-directly and indirectly require them.
-.PP
-\f[B]Options\f[R]
-.TP
-\f[I]options\f[R]
-See \f[B]Options for jmod\f[R].
-.PP
-\f[B]Required\f[R]
-.TP
-\f[I]jmod-file\f[R]
-Specifies the name of the JMOD file to create or from which to retrieve
-information.
-.SH DESCRIPTION
-.PP
-\f[B]Note:\f[R] For most development tasks, including deploying modules
-on the module path or publishing them to a Maven repository, continue to
-package modules in modular JAR files.
-The \f[V]jmod\f[R] tool is intended for modules that have native
-libraries or other configuration files or for modules that you intend to
-link, with the \f[B]jlink\f[R] tool, to a runtime image.
-.PP
-The JMOD file format lets you aggregate files other than
-\f[V].class\f[R] files, metadata, and resources.
-This format is transportable but not executable, which means that you
-can use it during compile time or link time but not at run time.
-.PP
-Many \f[V]jmod\f[R] options involve specifying a path whose contents are
-copied into the resulting JMOD files.
-These options copy all the contents of the specified path, including
-subdirectories and their contents, but exclude files whose names match
-the pattern specified by the \f[V]--exclude\f[R] option.
-.PP
-With the \f[V]--hash-modules\f[R] option or the \f[V]jmod hash\f[R]
-command, you can, in each module\[aq]s descriptor, record hashes of the
-content of the modules that are allowed to depend upon it, thus
-\[dq]tying\[dq] together these modules.
-This enables a package to be exported to one or more specifically-named
-modules and to no others through qualified exports.
-The runtime verifies if the recorded hash of a module matches the one
-resolved at run time; if not, the runtime returns an error.
-.SH OPTIONS FOR JMOD
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies the location of application JAR files or a directory
-containing classes to copy into the resulting JMOD file.
-.TP
-\f[V]--cmds\f[R] \f[I]path\f[R]
-Specifies the location of native commands to copy into the resulting
-JMOD file.
-.TP
-\f[V]--compress\f[R] \f[I]compress\f[R]
-Specifies the compression to use in creating the JMOD file.
-The accepted values are \f[V]zip-[0-9]\f[R], where \f[V]zip-0\f[R]
-provides no compression, and \f[V]zip-9\f[R] provides the best
-compression.
-Default is \f[V]zip-6\f[R].
-.TP
-\f[V]--config\f[R] \f[I]path\f[R]
-Specifies the location of user-editable configuration files to copy into
-the resulting JMOD file.
-.TP
-\f[V]--date\f[R]\f[I]TIMESTAMP\f[R]
-The timestamp in ISO-8601 extended offset date-time with optional
-time-zone format, to use for the timestamp of the entries, e.g.
-\[dq]2022-02-12T12:30:00-05:00\[dq].
-.TP
-\f[V]--dir\f[R] \f[I]path\f[R]
-Specifies the location where \f[V]jmod\f[R] puts extracted files from
-the specified JMOD archive.
-.TP
-\f[V]--dry-run\f[R]
-Performs a dry run of hash mode.
-It identifies leaf modules and their required modules without recording
-any hash values.
-.TP
-\f[V]--exclude\f[R] \f[I]pattern-list\f[R]
-Excludes files matching the supplied comma-separated pattern list, each
-element using one the following forms:
-.RS
-.IP \[bu] 2
-\f[I]glob-pattern\f[R]
-.IP \[bu] 2
-\f[V]glob:\f[R]\f[I]glob-pattern\f[R]
-.IP \[bu] 2
-\f[V]regex:\f[R]\f[I]regex-pattern\f[R]
-.PP
-See the \f[B]\f[VB]FileSystem.getPathMatcher\f[B]\f[R] method for the
-syntax of \f[I]glob-pattern\f[R].
-See the \f[B]\f[VB]Pattern\f[B]\f[R] class for the syntax of
-\f[I]regex-pattern\f[R], which represents a regular expression.
-.RE
-.TP
-\f[V]--hash-modules\f[R] \f[I]regex-pattern\f[R]
-Determines the leaf modules and records the hashes of the dependencies
-directly and indirectly requiring them, based on the module graph of the
-modules matching the given \f[I]regex-pattern\f[R].
-The hashes are recorded in the JMOD archive file being created, or a
-JMOD archive or modular JAR on the module path specified by the
-\f[V]jmod hash\f[R] command.
-.TP
-\f[V]--header-files\f[R] \f[I]path\f[R]
-Specifies the location of header files to copy into the resulting JMOD
-file.
-.TP
-\f[V]--help\f[R] or \f[V]-h\f[R]
-Prints a usage message.
-.TP
-\f[V]--help-extra\f[R]
-Prints help for extra options.
-.TP
-\f[V]--legal-notices\f[R] \f[I]path\f[R]
-Specifies the location of legal notices to copy into the resulting JMOD
-file.
-.TP
-\f[V]--libs\f[R] \f[I]path\f[R]
-Specifies location of native libraries to copy into the resulting JMOD
-file.
-.TP
-\f[V]--main-class\f[R] \f[I]class-name\f[R]
-Specifies main class to record in the module-info.class file.
-.TP
-\f[V]--man-pages\f[R] \f[I]path\f[R]
-Specifies the location of man pages to copy into the resulting JMOD
-file.
-.TP
-\f[V]--module-version\f[R] \f[I]module-version\f[R]
-Specifies the module version to record in the module-info.class file.
-.TP
-\f[V]--module-path\f[R] \f[I]path\f[R] or \f[V]-p\f[R] \f[I]path\f[R]
-Specifies the module path.
-This option is required if you also specify \f[V]--hash-modules\f[R].
-.TP
-\f[V]--target-platform\f[R] \f[I]platform\f[R]
-Specifies the target platform.
-.TP
-\f[V]--version\f[R]
-Prints version information of the \f[V]jmod\f[R] tool.
-.TP
-\f[V]\[at]\f[R]\f[I]filename\f[R]
-Reads options from the specified file.
-.RS
-.PP
-An options file is a text file that contains the options and values that
-you would ordinarily enter in a command prompt.
-Options may appear on one line or on several lines.
-You may not specify environment variables for path names.
-You may comment out lines by prefixinga hash symbol (\f[V]#\f[R]) to the
-beginning of the line.
-.PP
-The following is an example of an options file for the \f[V]jmod\f[R]
-command:
-.IP
-.nf
-\f[CB]
-#Wed Dec 07 00:40:19 EST 2016
-create --class-path mods/com.greetings --module-path mlib
-  --cmds commands --config configfiles --header-files src/h
-  --libs lib --main-class com.greetings.Main
-  --man-pages man --module-version 1.0
-  --os-arch \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
-  --os-version \[dq]10.10.5\[dq] greetingsmod
-\f[R]
-.fi
-.RE
-.SH EXTRA OPTIONS FOR JMOD
-.PP
-In addition to the options described in \f[B]Options for jmod\f[R], the
-following are extra options that can be used with the command.
-.TP
-\f[V]--do-not-resolve-by-default\f[R]
-Exclude from the default root set of modules
-.TP
-\f[V]--warn-if-resolved\f[R]
-Hint for a tool to issue a warning if the module is resolved.
-One of deprecated, deprecated-for-removal, or incubating.
-.SH JMOD CREATE EXAMPLE
-.PP
-The following is an example of creating a JMOD file:
-.IP
-.nf
-\f[CB]
-jmod create --class-path mods/com.greetings --cmds commands
-  --config configfiles --header-files src/h --libs lib
-  --main-class com.greetings.Main --man-pages man --module-version 1.0
-  --os-arch \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
-  --os-version \[dq]10.10.5\[dq] greetingsmod
-\f[R]
-.fi
-.PP
-Create a JMOD file specifying the date for the entries as
-\f[V]2022 March 15 00:00:00\f[R]:
-.IP
-.nf
-\f[CB]
-jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
-   jmods/foo1.jmod
-\f[R]
-.fi
-.SH JMOD HASH EXAMPLE
-.PP
-The following example demonstrates what happens when you try to link a
-leaf module (in this example, \f[V]ma\f[R]) with a required module
-(\f[V]mb\f[R]), and the hash value recorded in the required module
-doesn\[aq]t match that of the leaf module.
-.IP "1." 3
-Create and compile the following \f[V].java\f[R] files:
-.RS 4
-.IP \[bu] 2
-\f[V]jmodhashex/src/ma/module-info.java\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-module ma {
-  requires mb;
-}
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[V]jmodhashex/src/mb/module-info.java\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-module mb {
-}
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[V]jmodhashex2/src/ma/module-info.java\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-module ma {
-  requires mb;
-}
-\f[R]
-.fi
-.RE
-.IP \[bu] 2
-\f[V]jmodhashex2/src/mb/module-info.java\f[R]
-.RS 2
-.IP
-.nf
-\f[CB]
-module mb {
-}
-\f[R]
-.fi
-.RE
-.RE
-.IP "2." 3
-Create a JMOD archive for each module.
-Create the directories \f[V]jmodhashex/jmods\f[R] and
-\f[V]jmodhashex2/jmods\f[R], and then run the following commands from
-the \f[V]jmodhashex\f[R] directory, then from the \f[V]jmodhashex2\f[R]
-directory:
-.RS 4
-.IP \[bu] 2
-\f[V]jmod create --class-path mods/ma jmods/ma.jmod\f[R]
-.IP \[bu] 2
-\f[V]jmod create --class-path mods/mb jmods/mb.jmod\f[R]
-.RE
-.IP "3." 3
-Optionally preview the \f[V]jmod hash\f[R] command.
-Run the following command from the \f[V]jmodhashex\f[R] directory:
-.RS 4
-.PP
-\f[V]jmod hash --dry-run -module-path jmods --hash-modules .*\f[R]
-.PP
-The command prints the following:
-.IP
-.nf
-\f[CB]
-Dry run:
-mb
-  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
-\f[R]
-.fi
-.PP
-This indicates that the \f[V]jmod hash\f[R] command (without the
-\f[V]--dry-run\f[R] option) will record the hash value of the leaf
-module \f[V]ma\f[R] in the module \f[V]mb\f[R].
-.RE
-.IP "4." 3
-Record hash values in the JMOD archive files contained in the
-\f[V]jmodhashex\f[R] directory.
-Run the following command from the \f[V]jmodhashex\f[R] directory:
-.RS 4
-.RS
-.PP
-\f[V]jmod hash --module-path jmods --hash-modules .*\f[R]
-.RE
-.PP
-The command prints the following:
-.RS
-.PP
-\f[V]Hashes are recorded in module mb\f[R]
-.RE
-.RE
-.IP "5." 3
-Print information about each JMOD archive contained in the
-\f[V]jmodhashex\f[R] directory.
-Run the highlighted commands from the \f[V]jmodhashex\f[R] directory:
-.RS 4
-.IP
-.nf
-\f[CB]
-jmod describe jmods/ma.jmod
-
-ma
-  requires mandated java.base
-  requires mb
-
-jmod describe jmods/mb.jmod
-
-mb
-  requires mandated java.base
-  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
-\f[R]
-.fi
-.RE
-.IP "6." 3
-Attempt to create a runtime image that contains the module \f[V]ma\f[R]
-from the directory \f[V]jmodhashex2\f[R] but the module \f[V]mb\f[R]
-from the directory \f[V]jmodhashex\f[R].
-Run the following command from the \f[V]jmodhashex2\f[R] directory:
-.RS 4
-.IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]jlink --module-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
-.RE
-.RE
-.IP \[bu] 2
-\f[B]Windows:\f[R]
-.RS 2
-.RS
-.PP
-\f[V]jlink --module-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
-.RE
-.RE
-.PP
-The command prints an error message similar to the following:
-.IP
-.nf
-\f[CB]
-Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
-expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
-\f[R]
-.fi
-.RE
diff --git a/src/jdk.jlink/share/man/jmod.md b/src/jdk.jlink/share/man/jmod.md
new file mode 100644
index 00000000000..273001b6a9a
--- /dev/null
+++ b/src/jdk.jlink/share/man/jmod.md
@@ -0,0 +1,348 @@
+---
+# Copyright (c) 2017, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JMOD(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jmod - create JMOD files and list the content of existing JMOD files
+
+## Synopsis
+
+`jmod` (`create`\|`extract`\|`list`\|`describe`\|`hash`) \[*options*\]
+*jmod-file*
+
+Includes the following:
+
+**Main operation modes**
+
+`create`
+:   Creates a new JMOD archive file.
+
+`extract`
+:   Extracts all the files from the JMOD archive file.
+
+`list`
+:   Prints the names of all the entries.
+
+`describe`
+:   Prints the module details.
+
+`hash`
+:   Determines leaf modules and records the hashes of the dependencies that
+    directly and indirectly require them.
+
+**Options**
+
+*options*
+:   See [Options for jmod].
+
+**Required**
+
+*jmod-file*
+:   Specifies the name of the JMOD file to create or from which to retrieve
+    information.
+
+## Description
+
+**Note:** For most development tasks, including deploying modules on the module
+path or publishing them to a Maven repository, continue to package modules in
+modular JAR files. The `jmod` tool is intended for modules that have native
+libraries or other configuration files or for modules that you intend to link,
+with the [jlink](jlink.html) tool, to a runtime image.
+
+The JMOD file format lets you aggregate files other than `.class` files,
+metadata, and resources. This format is transportable but not executable, which
+means that you can use it during compile time or link time but not at run time.
+
+Many `jmod` options involve specifying a path whose contents are copied into
+the resulting JMOD files. These options copy all the contents of the specified
+path, including subdirectories and their contents, but exclude files whose
+names match the pattern specified by the `--exclude` option.
+
+With the `--hash-modules` option or the `jmod hash` command, you can, in each
+module's descriptor, record hashes of the content of the modules that are
+allowed to depend upon it, thus "tying" together these modules. This enables a
+package to be exported to one or more specifically-named modules and to no
+others through qualified exports. The runtime verifies if the recorded hash of
+a module matches the one resolved at run time; if not, the runtime returns an
+error.
+
+## Options for jmod
+
+`--class-path` *path*
+:   Specifies the location of application JAR files or a directory containing
+    classes to copy into the resulting JMOD file.
+
+`--cmds` *path*
+:   Specifies the location of native commands to copy into the resulting JMOD
+    file.
+
+`--compress` *compress*
+:   Specifies the compression to use in creating the JMOD file.
+    The accepted values are `zip-[0-9]`, where `zip-0` provides no
+    compression, and `zip-9` provides the best compression. Default is `zip-6`.
+
+`--config` *path*
+:   Specifies the location of user-editable configuration files to copy into
+    the resulting JMOD file.
+
+`--date `*TIMESTAMP*
+:   The timestamp in ISO-8601 extended offset date-time with optional time-zone
+format, to use for the timestamp of the entries,
+e.g. "2022-02-12T12:30:00-05:00".
+
+`--dir` *path*
+:   Specifies the location where `jmod` puts extracted files from the specified
+    JMOD archive.
+
+`--dry-run`
+:   Performs a dry run of hash mode. It identifies leaf modules and their
+    required modules without recording any hash values.
+
+`--exclude` *pattern-list*
+:   Excludes files matching the supplied comma-separated pattern list, each
+    element using one the following forms:
+
+    -   *glob-pattern*
+
+    -   `glob:`*glob-pattern*
+
+    -   `regex:`*regex-pattern*
+
+    See the [`FileSystem.getPathMatcher`](
+    ../../api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String))
+    method for the syntax of *glob-pattern*. See the [`Pattern`](
+    ../../api/java.base/java/util/regex/Pattern.html)
+    class for the syntax of *regex-pattern*, which represents a regular
+    expression.
+
+`--hash-modules` *regex-pattern*
+:   Determines the leaf modules and records the hashes of the dependencies
+    directly and indirectly requiring them, based on the module graph of the
+    modules matching the given *regex-pattern*. The hashes are recorded in the
+    JMOD archive file being created, or a JMOD archive or modular JAR on the
+    module path specified by the `jmod hash` command.
+
+`--header-files` *path*
+:   Specifies the location of header files to copy into the resulting JMOD
+    file.
+
+`--help` or `-h`
+:   Prints a usage message.
+
+`--help-extra`
+:   Prints help for extra options.
+
+`--legal-notices` *path*
+:   Specifies the location of legal notices to copy into the resulting JMOD
+    file.
+
+`--libs` *path*
+:   Specifies location of native libraries to copy into the resulting JMOD
+    file.
+
+`--main-class` *class-name*
+:   Specifies main class to record in the module-info.class file.
+
+`--man-pages` *path*
+:   Specifies the location of man pages to copy into the resulting JMOD file.
+
+`--module-version` *module-version*
+:   Specifies the module version to record in the module-info.class file.
+
+`--module-path` *path* or `-p` *path*
+:   Specifies the module path. This option is required if you also specify
+    `--hash-modules`.
+
+`--target-platform` *platform*
+:   Specifies the target platform.
+
+`--version`
+:   Prints version information of the `jmod` tool.
+
+`@`*filename*
+:   Reads options from the specified file.
+
+    An options file is a text file that contains the options and values that
+    you would ordinarily enter in a command prompt. Options may appear on one
+    line or on several lines. You may not specify environment variables for
+    path names. You may comment out lines by prefixinga hash symbol (`#`) to
+    the beginning of the line.
+
+    The following is an example of an options file for the `jmod` command:
+
+    ```
+    #Wed Dec 07 00:40:19 EST 2016
+    create --class-path mods/com.greetings --module-path mlib
+      --cmds commands --config configfiles --header-files src/h
+      --libs lib --main-class com.greetings.Main
+      --man-pages man --module-version 1.0
+      --os-arch "x86_x64" --os-name "macOS"
+      --os-version "10.10.5" greetingsmod
+    ```
+
+## Extra Options for jmod
+
+In addition to the options described in [Options for jmod], the following are
+extra options that can be used with the command.
+
+`--do-not-resolve-by-default`
+:   Exclude from the default root set of modules
+
+`--warn-if-resolved`
+:   Hint for a tool to issue a warning if the module is resolved. One of
+    deprecated, deprecated-for-removal, or incubating.
+
+## jmod Create Example
+
+The following is an example of creating a JMOD file:
+
+```
+jmod create --class-path mods/com.greetings --cmds commands
+  --config configfiles --header-files src/h --libs lib
+  --main-class com.greetings.Main --man-pages man --module-version 1.0
+  --os-arch "x86_x64" --os-name "macOS"
+  --os-version "10.10.5" greetingsmod
+```
+Create a JMOD file specifying the date for the entries as `2022 March 15 00:00:00`:
+
+```
+jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
+   jmods/foo1.jmod
+```
+## jmod Hash Example
+
+The following example demonstrates what happens when you try to link a leaf
+module (in this example, `ma`) with a required module (`mb`), and the hash
+value recorded in the required module doesn't match that of the leaf module.
+
+1.  Create and compile the following `.java` files:
+
+    -   `jmodhashex/src/ma/module-info.java`
+
+        ```
+        module ma {
+          requires mb;
+        }
+        ```
+
+    -   `jmodhashex/src/mb/module-info.java`
+
+        ```
+        module mb {
+        }
+        ```
+
+    -   `jmodhashex2/src/ma/module-info.java`
+
+        ```
+        module ma {
+          requires mb;
+        }
+        ```
+
+    -   `jmodhashex2/src/mb/module-info.java`
+
+        ```
+        module mb {
+        }
+        ```
+
+2.  Create a JMOD archive for each module. Create the directories
+    `jmodhashex/jmods` and `jmodhashex2/jmods`, and then run the following
+    commands from the `jmodhashex` directory, then from the `jmodhashex2`
+    directory:
+
+    -   `jmod create --class-path mods/ma jmods/ma.jmod`
+
+    -   `jmod create --class-path mods/mb jmods/mb.jmod`
+
+3.  Optionally preview the `jmod hash` command. Run the following command from
+    the `jmodhashex` directory:
+
+    `jmod hash --dry-run -module-path jmods --hash-modules .*`
+
+    The command prints the following:
+
+    ```
+    Dry run:
+    mb
+      hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
+    ```
+
+    This indicates that the `jmod hash` command (without the `--dry-run`
+    option) will record the hash value of the leaf module `ma` in the module
+    `mb`.
+
+4.  Record hash values in the JMOD archive files contained in the `jmodhashex`
+    directory. Run the following command from the `jmodhashex` directory:
+
+    >   `jmod hash --module-path jmods --hash-modules .*`
+
+    The command prints the following:
+
+    >   `Hashes are recorded in module mb`
+
+5.  Print information about each JMOD archive contained in the `jmodhashex`
+    directory. Run the highlighted commands from the `jmodhashex` directory:
+
+    ```
+    jmod describe jmods/ma.jmod
+
+    ma
+      requires mandated java.base
+      requires mb
+
+    jmod describe jmods/mb.jmod
+
+    mb
+      requires mandated java.base
+      hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
+    ```
+
+6.  Attempt to create a runtime image that contains the module `ma` from the
+    directory `jmodhashex2` but the module `mb` from the directory
+    `jmodhashex`. Run the following command from the `jmodhashex2` directory:
+
+    -   **Linux and macOS:**
+
+        >   `jlink --module-path
+            $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod
+            --add-modules ma --output ma-app`
+
+    -   **Windows:**
+
+        >   `jlink --module-path
+            %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod
+            --add-modules ma --output ma-app`
+
+    The command prints an error message similar to the following:
+
+    ```
+    Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
+    expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
+    ```
diff --git a/src/jdk.jpackage/share/man/jpackage.1 b/src/jdk.jpackage/share/man/jpackage.1
deleted file mode 100644
index 09d340ec033..00000000000
--- a/src/jdk.jpackage/share/man/jpackage.1
+++ /dev/null
@@ -1,834 +0,0 @@
-.\" Copyright (c) 2018, 2024, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JPACKAGE" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jpackage - tool for packaging self-contained Java applications.
-.SH SYNOPSIS
-.PP
-\f[V]jpackage\f[R] [\f[I]options\f[R]]
-.TP
-\f[I]options\f[R]
-Command-line options separated by spaces.
-See \f[B]jpackage Options\f[R].
-.SH DESCRIPTION
-.PP
-The \f[V]jpackage\f[R] tool will take as input a Java application and a
-Java run-time image, and produce a Java application image that includes
-all the necessary dependencies.
-It will be able to produce a native package in a platform-specific
-format, such as an exe on Windows or a dmg on macOS.
-Each format must be built on the platform it runs on, there is no
-cross-platform support.
-The tool will have options that allow packaged applications to be
-customized in various ways.
-.SH JPACKAGE OPTIONS
-.SS Generic Options:
-.TP
-\f[V]\[at]\f[R]\f[I]filename\f[R]
-Read options from a file.
-.RS
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--type\f[R] or \f[V]-t\f[R] \f[I]type\f[R]
-The type of package to create
-.RS
-.PP
-Valid values are: {\[dq]app-image\[dq], \[dq]exe\[dq], \[dq]msi\[dq],
-\[dq]rpm\[dq], \[dq]deb\[dq], \[dq]pkg\[dq], \[dq]dmg\[dq]}
-.PP
-If this option is not specified a platform dependent default type will
-be created.
-.RE
-.TP
-\f[V]--app-version\f[R] \f[I]version\f[R]
-Version of the application and/or package
-.TP
-\f[V]--copyright\f[R] \f[I]copyright\f[R]
-Copyright for the application
-.TP
-\f[V]--description\f[R] \f[I]description\f[R]
-Description of the application
-.TP
-\f[V]--help\f[R] or \f[V]-h\f[R]
-Print the usage text with a list and description of each valid option
-for the current platform to the output stream, and exit.
-.TP
-\f[V]--icon\f[R] \f[I]path\f[R]
-Path of the icon of the application package
-.RS
-.PP
-(absolute path or relative to the current directory)
-.RE
-.TP
-\f[V]--name\f[R] or \f[V]-n\f[R] \f[I]name\f[R]
-Name of the application and/or package
-.TP
-\f[V]--dest\f[R] or \f[V]-d\f[R] \f[I]destination\f[R]
-Path where generated output file is placed
-.RS
-.PP
-(absolute path or relative to the current directory).
-.PP
-Defaults to the current working directory.
-.RE
-.TP
-\f[V]--resource-dir\f[R] \f[I]path\f[R]
-Path to override jpackage resources
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-Icons, template files, and other resources of jpackage can be
-over-ridden by adding replacement resources to this directory.
-.RE
-.TP
-\f[V]--temp\f[R] \f[I]directory\f[R]
-Path of a new or empty directory used to create temporary files
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-If specified, the temp dir will not be removed upon the task completion
-and must be removed manually.
-.PP
-If not specified, a temporary directory will be created and removed upon
-the task completion.
-.RE
-.TP
-\f[V]--vendor\f[R] \f[I]vendor\f[R]
-Vendor of the application
-.TP
-\f[V]--verbose\f[R]
-Enables verbose output.
-.TP
-\f[V]--version\f[R]
-Print the product version to the output stream and exit.
-.SS Options for creating the runtime image:
-.TP
-\f[V]--add-modules\f[R] \f[I]module-name\f[R] [\f[V],\f[R]\f[I]module-name\f[R]...]
-A comma (\[dq],\[dq]) separated list of modules to add
-.RS
-.PP
-This module list, along with the main module (if specified) will be
-passed to jlink as the --add-module argument.
-If not specified, either just the main module (if --module is
-specified), or the default set of modules (if --main-jar is specified)
-are used.
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--module-path\f[R] or \f[V]-p\f[R] \f[I]module-path\f[R] [\f[V],\f[R]\f[I]module-path\f[R]...]
-A File.pathSeparator separated list of paths
-.RS
-.PP
-Each path is either a directory of modules or the path to a modular jar,
-and is absolute or relative to the current directory.
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--jlink-options\f[R] \f[I]options\f[R]
-A space separated list of options to pass to jlink
-.RS
-.PP
-If not specified, defaults to \[dq]--strip-native-commands --strip-debug
---no-man-pages --no-header-files\[dq]
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--runtime-image\f[R] \f[I]directory\f[R]
-Path of the predefined runtime image that will be copied into the
-application image
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-If --runtime-image is not specified, jpackage will run jlink to create
-the runtime image using options specified by --jlink-options.
-.RE
-.SS Options for creating the application image:
-.TP
-\f[V]--input\f[R] or \f[V]-i\f[R] \f[I]directory\f[R]
-Path of the input directory that contains the files to be packaged
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-All files in the input directory will be packaged into the application
-image.
-.RE
-.TP
-\f[V]--app-content\f[R] \f[I]additional-content\f[R] [\f[V],\f[R]\f[I]additional-content\f[R]...]
-A comma separated list of paths to files and/or directories to add to
-the application payload.
-.RS
-.PP
-This option can be used more than once.
-.RE
-.SS Options for creating the application launcher(s):
-.TP
-\f[V]--add-launcher\f[R] \f[I]name\f[R]=\f[I]path\f[R]
-Name of launcher, and a path to a Properties file that contains a list
-of key, value pairs
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-The keys \[dq]module\[dq], \[dq]main-jar\[dq], \[dq]main-class\[dq],
-\[dq]description\[dq], \[dq]arguments\[dq], \[dq]java-options\[dq],
-\[dq]icon\[dq], \[dq]launcher-as-service\[dq], \[dq]win-console\[dq],
-\[dq]win-shortcut\[dq], \[dq]win-menu\[dq], and \[dq]linux-shortcut\[dq]
-can be used.
-.PP
-These options are added to, or used to overwrite, the original command
-line options to build an additional alternative launcher.
-The main application launcher will be built from the command line
-options.
-Additional alternative launchers can be built using this option, and
-this option can be used multiple times to build multiple additional
-launchers.
-.RE
-.TP
-\f[V]--arguments\f[R] \f[I]arguments\f[R]
-Command line arguments to pass to the main class if no command line
-arguments are given to the launcher
-.RS
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--java-options\f[R] \f[I]options\f[R]
-Options to pass to the Java runtime
-.RS
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--main-class\f[R] \f[I]class-name\f[R]
-Qualified name of the application main class to execute
-.RS
-.PP
-This option can only be used if --main-jar is specified.
-.RE
-.TP
-\f[V]--main-jar\f[R] \f[I]main-jar\f[R]
-The main JAR of the application; containing the main class (specified as
-a path relative to the input path)
-.RS
-.PP
-Either --module or --main-jar option can be specified but not both.
-.RE
-.TP
-\f[V]--module\f[R] or \f[V]-m\f[R] \f[I]module-name\f[R][/\f[I]main-class\f[R]]
-The main module (and optionally main class) of the application
-.RS
-.PP
-This module must be located on the module path.
-.PP
-When this option is specified, the main module will be linked in the
-Java runtime image.
-Either --module or --main-jar option can be specified but not both.
-.RE
-.SS Platform dependent options for creating the application launcher:
-.SS Windows platform options (available only when running on Windows):
-.TP
-\f[V]--win-console\f[R]
-Creates a console launcher for the application, should be specified for
-application which requires console interactions
-.SS macOS platform options (available only when running on macOS):
-.TP
-\f[V]--mac-package-identifier\f[R] \f[I]identifier\f[R]
-An identifier that uniquely identifies the application for macOS
-.RS
-.PP
-Defaults to the main class name.
-.PP
-May only use alphanumeric (A-Z,a-z,0-9), hyphen (-), and period (.)
-characters.
-.RE
-.TP
-\f[V]--mac-package-name\f[R] \f[I]name\f[R]
-Name of the application as it appears in the Menu Bar
-.RS
-.PP
-This can be different from the application name.
-.PP
-This name must be less than 16 characters long and be suitable for
-displaying in the menu bar and the application Info window.
-Defaults to the application name.
-.RE
-.TP
-\f[V]--mac-package-signing-prefix\f[R] \f[I]prefix\f[R]
-When signing the application package, this value is prefixed to all
-components that need to be signed that don\[aq]t have an existing
-package identifier.
-.TP
-\f[V]--mac-sign\f[R]
-Request that the package or the predefined application image be signed.
-.TP
-\f[V]--mac-signing-keychain\f[R] \f[I]keychain-name\f[R]
-Name of the keychain to search for the signing identity
-.RS
-.PP
-If not specified, the standard keychains are used.
-.RE
-.TP
-\f[V]--mac-signing-key-user-name\f[R] \f[I]name\f[R]
-Team or user name portion in Apple signing identities
-.TP
-\f[V]--mac-app-store\f[R]
-Indicates that the jpackage output is intended for the Mac App Store.
-.TP
-\f[V]--mac-entitlements\f[R] \f[I]path\f[R]
-Path to file containing entitlements to use when signing executables and
-libraries in the bundle
-.TP
-\f[V]--mac-app-category\f[R] \f[I]category\f[R]
-String used to construct LSApplicationCategoryType in application plist
-.RS
-.PP
-The default value is \[dq]utilities\[dq].
-.RE
-.SS Options for creating the application package:
-.TP
-\f[V]--about-url\f[R] \f[I]url\f[R]
-URL of the application\[aq]s home page
-.TP
-\f[V]--app-image\f[R] \f[I]directory\f[R]
-Location of the predefined application image that is used to build an
-installable package (on all platforms) or to be signed (on macOS)
-.RS
-.PP
-(absolute path or relative to the current directory)
-.RE
-.TP
-\f[V]--file-associations\f[R] \f[I]path\f[R]
-Path to a Properties file that contains list of key, value pairs
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-The keys \[dq]extension\[dq], \[dq]mime-type\[dq], \[dq]icon\[dq], and
-\[dq]description\[dq] can be used to describe the association.
-.PP
-This option can be used multiple times.
-.RE
-.TP
-\f[V]--install-dir\f[R] \f[I]path\f[R]
-Absolute path of the installation directory of the application (on macOS
-or linux), or relative sub-path of the installation directory such as
-\[dq]Program Files\[dq] or \[dq]AppData\[dq] (on Windows)
-.TP
-\f[V]--license-file\f[R] \f[I]path\f[R]
-Path to the license file
-.RS
-.PP
-(absolute path or relative to the current directory)
-.RE
-.TP
-\f[V]--runtime-image\f[R] \f[I]path\f[R]
-Path of the predefined runtime image to install
-.RS
-.PP
-(absolute path or relative to the current directory)
-.PP
-Option is required when creating a runtime installer.
-.RE
-.TP
-\f[V]--launcher-as-service\f[R]
-Request to create an installer that will register the main application
-launcher as a background service-type application.
-.SS Platform dependent options for creating the application package:
-.SS Windows platform options (available only when running on Windows):
-.TP
-\f[V]--win-dir-chooser\f[R]
-Adds a dialog to enable the user to choose a directory in which the
-product is installed.
-.TP
-\f[V]--win-help-url\f[R] \f[I]url\f[R]
-URL where user can obtain further information or technical support
-.TP
-\f[V]--win-menu\f[R]
-Request to add a Start Menu shortcut for this application
-.TP
-\f[V]--win-menu-group\f[R] \f[I]menu-group-name\f[R]
-Start Menu group this application is placed in
-.TP
-\f[V]--win-per-user-install\f[R]
-Request to perform an install on a per-user basis
-.TP
-\f[V]--win-shortcut\f[R]
-Request to create a desktop shortcut for this application
-.TP
-\f[V]--win-shortcut-prompt\f[R]
-Adds a dialog to enable the user to choose if shortcuts will be created
-by installer
-.TP
-\f[V]--win-update-url\f[R] \f[I]url\f[R]
-URL of available application update information
-.TP
-\f[V]--win-upgrade-uuid\f[R] \f[I]id\f[R]
-UUID associated with upgrades for this package
-.SS Linux platform options (available only when running on Linux):
-.TP
-\f[V]--linux-package-name\f[R] \f[I]name\f[R]
-Name for Linux package
-.RS
-.PP
-Defaults to the application name.
-.RE
-.TP
-\f[V]--linux-deb-maintainer\f[R] \f[I]email-address\f[R]
-Maintainer for .deb bundle
-.TP
-\f[V]--linux-menu-group\f[R] \f[I]menu-group-name\f[R]
-Menu group this application is placed in
-.TP
-\f[V]--linux-package-deps\f[R]
-Required packages or capabilities for the application
-.TP
-\f[V]--linux-rpm-license-type\f[R] \f[I]type\f[R]
-Type of the license (\[dq]License: \f[I]value\f[R]\[dq] of the RPM
-\&.spec)
-.TP
-\f[V]--linux-app-release\f[R] \f[I]release\f[R]
-Release value of the RPM <name>.spec file or Debian revision value of
-the DEB control file
-.TP
-\f[V]--linux-app-category\f[R] \f[I]category-value\f[R]
-Group value of the RPM /.spec file or Section value of DEB control file
-.TP
-\f[V]--linux-shortcut\f[R]
-Creates a shortcut for the application.
-.SS macOS platform options (available only when running on macOS):
-.TP
-\f[V]--mac-dmg-content\f[R] \f[I]additional-content\f[R] [\f[V],\f[R]\f[I]additional-content\f[R]...]
-Include all the referenced content in the dmg.
-.RS
-.PP
-This option can be used more than once.
-.RE
-.SH JPACKAGE EXAMPLES
-.IP
-.nf
-\f[CB]
-Generate an application package suitable for the host system:
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-For a modular application:
-    jpackage -n name -p modulePath -m moduleName/className
-For a non-modular application:
-    jpackage -i inputDir -n name \[rs]
-        --main-class className --main-jar myJar.jar
-From a pre-built application image:
-    jpackage -n name --app-image appImageDir
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-Generate an application image:
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-For a modular application:
-    jpackage --type app-image -n name -p modulePath \[rs]
-        -m moduleName/className
-For a non-modular application:
-    jpackage --type app-image -i inputDir -n name \[rs]
-        --main-class className --main-jar myJar.jar
-To provide your own options to jlink, run jlink separately:
-    jlink --output appRuntimeImage -p modulePath \[rs]
-        --add-modules moduleName \[rs]
-        --no-header-files [<additional jlink options>...]
-    jpackage --type app-image -n name \[rs]
-        -m moduleName/className --runtime-image appRuntimeImage
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-Generate a Java runtime package:
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-jpackage -n name --runtime-image <runtime-image>
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-Sign the predefined application image (on macOS):
-\f[R]
-.fi
-.IP
-.nf
-\f[CB]
-jpackage --type app-image --app-image <app-image> \[rs]
-    --mac-sign [<additional signing options>...]
-
-Note: the only additional options that are permitted in this mode are:
-      the set of additional mac signing options and --verbose
-\f[R]
-.fi
-.SH JPACKAGE RESOURCE DIRECTORY
-.PP
-Icons, template files, and other resources of jpackage can be
-over-ridden by adding replacement resources to this directory.
-jpackage will lookup files by specific names in the resource directory.
-.SS Resource directory files considered only when running on Linux:
-.TP
-\f[V]<launcher-name>.png\f[R]
-Application launcher icon
-.RS
-.PP
-Default resource is \f[I]JavaApp.png\f[R]
-.RE
-.TP
-\f[V]<launcher-name>.desktop\f[R]
-A desktop file to be used with \f[V]xdg-desktop-menu\f[R] command
-.RS
-.PP
-Considered with application launchers registered for file associations
-and/or have an icon
-.PP
-Default resource is \f[I]template.desktop\f[R]
-.RE
-.SS Resource directory files considered only when building Linux DEB/RPM installer:
-.TP
-\f[V]<package-name>-<launcher-name>.service\f[R]
-systemd unit file for application launcher registered as a background
-service-type application
-.RS
-.PP
-Default resource is \f[I]unit-template.service\f[R]
-.RE
-.SS Resource directory files considered only when building Linux RPM installer:
-.TP
-\f[V]<package-name>.spec\f[R]
-RPM spec file
-.RS
-.PP
-Default resource is \f[I]template.spec\f[R]
-.RE
-.SS Resource directory files considered only when building Linux DEB installer:
-.TP
-\f[V]control\f[R]
-Control file
-.RS
-.PP
-Default resource is \f[I]template.control\f[R]
-.RE
-.TP
-\f[V]copyright\f[R]
-Copyright file
-.RS
-.PP
-Default resource is \f[I]template.copyright\f[R]
-.RE
-.TP
-\f[V]preinstall\f[R]
-Pre-install shell script
-.RS
-.PP
-Default resource is \f[I]template.preinstall\f[R]
-.RE
-.TP
-\f[V]prerm\f[R]
-Pre-remove shell script
-.RS
-.PP
-Default resource is \f[I]template.prerm\f[R]
-.RE
-.TP
-\f[V]postinstall\f[R]
-Post-install shell script
-.RS
-.PP
-Default resource is \f[I]template.postinstall\f[R]
-.RE
-.TP
-\f[V]postrm\f[R]
-Post-remove shell script
-.RS
-.PP
-Default resource is \f[I]template.postrm\f[R]
-.RE
-.SS Resource directory files considered only when running on Windows:
-.TP
-\f[V]<launcher-name>.ico\f[R]
-Application launcher icon
-.RS
-.PP
-Default resource is \f[I]JavaApp.ico\f[R]
-.RE
-.TP
-\f[V]<launcher-name>.properties\f[R]
-Properties file for application launcher executable
-.RS
-.PP
-Default resource is \f[I]WinLauncher.template\f[R]
-.RE
-.SS Resource directory files considered only when building Windows MSI/EXE installer:
-.TP
-\f[V]<application-name>-post-image.wsf\f[R]
-A Windows Script File (WSF) to run after building application image
-.TP
-\f[V]main.wxs\f[R]
-Main WiX project file
-.RS
-.PP
-Default resource is \f[I]main.wxs\f[R]
-.RE
-.TP
-\f[V]overrides.wxi\f[R]
-Overrides WiX project file
-.RS
-.PP
-Default resource is \f[I]overrides.wxi\f[R]
-.RE
-.TP
-\f[V]service-installer.exe\f[R]
-Service installer executable
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.RE
-.TP
-\f[V]<launcher-name>-service-install.wxi\f[R]
-Service installer WiX project file
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.PP
-Default resource is \f[I]service-install.wxi\f[R]
-.RE
-.TP
-\f[V]<launcher-name>-service-config.wxi\f[R]
-Service installer WiX project file
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.PP
-Default resource is \f[I]service-config.wxi\f[R]
-.RE
-.TP
-\f[V]InstallDirNotEmptyDlg.wxs\f[R]
-WiX project file for installer UI dialog checking installation directory
-doesn\[aq]t exist or is empty
-.RS
-.PP
-Default resource is \f[I]InstallDirNotEmptyDlg.wxs\f[R]
-.RE
-.TP
-\f[V]ShortcutPromptDlg.wxs\f[R]
-WiX project file for installer UI dialog configuring shortcuts
-.RS
-.PP
-Default resource is \f[I]ShortcutPromptDlg.wxs\f[R]
-.RE
-.TP
-\f[V]bundle.wxf\f[R]
-WiX project file with the hierarchy of components of application image
-.TP
-\f[V]ui.wxf\f[R]
-WiX project file for installer UI
-.SS Resource directory files considered only when building Windows EXE installer:
-.TP
-\f[V]WinInstaller.properties\f[R]
-Properties file for the installer executable
-.RS
-.PP
-Default resource is \f[I]WinInstaller.template\f[R]
-.RE
-.TP
-\f[V]<package-name>-post-msi.wsf\f[R]
-A Windows Script File (WSF) to run after building embedded MSI installer
-for EXE installer
-.SS Resource directory files considered only when running on macOS:
-.TP
-\f[V]<launcher-name>.icns\f[R]
-Application launcher icon
-.RS
-.PP
-Default resource is \f[I]JavaApp.icns\f[R]
-.RE
-.TP
-\f[V]Info.plist\f[R]
-Application property list file
-.RS
-.PP
-Default resource is \f[I]Info-lite.plist.template\f[R]
-.RE
-.TP
-\f[V]Runtime-Info.plist\f[R]
-Java Runtime property list file
-.RS
-.PP
-Default resource is \f[I]Runtime-Info.plist.template\f[R]
-.RE
-.TP
-\f[V]<application-name>.entitlements\f[R]
-Signing entitlements property list file
-.RS
-.PP
-Default resource is \f[I]sandbox.plist\f[R]
-.RE
-.SS Resource directory files considered only when building macOS PKG/DMG installer:
-.TP
-\f[V]<package-name>-post-image.sh\f[R]
-Shell script to run after building application image
-.SS Resource directory files considered only when building macOS PKG installer:
-.TP
-\f[V]uninstaller\f[R]
-Uninstaller shell script
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.PP
-Default resource is \f[I]uninstall.command.template\f[R]
-.RE
-.TP
-\f[V]preinstall\f[R]
-Pre-install shell script
-.RS
-.PP
-Default resource is \f[I]preinstall.template\f[R]
-.RE
-.TP
-\f[V]postinstall\f[R]
-Post-install shell script
-.RS
-.PP
-Default resource is \f[I]postinstall.template\f[R]
-.RE
-.TP
-\f[V]services-preinstall\f[R]
-Pre-install shell script for services package
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.PP
-Default resource is \f[I]services-preinstall.template\f[R]
-.RE
-.TP
-\f[V]services-postinstall\f[R]
-Post-install shell script for services package
-.RS
-.PP
-Considered if some application launchers are registered as background
-service-type applications
-.PP
-Default resource is \f[I]services-postinstall.template\f[R]
-.RE
-.TP
-\f[V]<package-name>-background.png\f[R]
-Background image
-.RS
-.PP
-Default resource is \f[I]background_pkg.png\f[R]
-.RE
-.TP
-\f[V]<package-name>-background-darkAqua.png\f[R]
-Dark background image
-.RS
-.PP
-Default resource is \f[I]background_pkg.png\f[R]
-.RE
-.TP
-\f[V]product-def.plist\f[R]
-Package property list file
-.RS
-.PP
-Default resource is \f[I]product-def.plist\f[R]
-.RE
-.TP
-\f[V]<package-name>-<launcher-name>.plist\f[R]
-launchd property list file for application launcher registered as a
-background service-type application
-.RS
-.PP
-Default resource is \f[I]launchd.plist.template\f[R]
-.RE
-.SS Resource directory files considered only when building macOS DMG installer:
-.TP
-\f[V]<package-name>-dmg-setup.scpt\f[R]
-Setup AppleScript script
-.RS
-.PP
-Default resource is \f[I]DMGsetup.scpt\f[R]
-.RE
-.TP
-\f[V]<package-name>-license.plist\f[R]
-License property list file
-.RS
-.PP
-Default resource is \f[I]lic_template.plist\f[R]
-.RE
-.TP
-\f[V]<package-name>-background.tiff\f[R]
-Background image
-.RS
-.PP
-Default resource is \f[I]background_dmg.tiff\f[R]
-.RE
-.TP
-\f[V]<package-name>-volume.icns\f[R]
-Volume icon
-.RS
-.PP
-Default resource is \f[I]JavaApp.icns\f[R]
-.RE
diff --git a/src/jdk.jpackage/share/man/jpackage.md b/src/jdk.jpackage/share/man/jpackage.md
new file mode 100644
index 00000000000..228c0b13259
--- /dev/null
+++ b/src/jdk.jpackage/share/man/jpackage.md
@@ -0,0 +1,791 @@
+---
+# Copyright (c) 2018, 2024, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JPACKAGE(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jpackage - tool for packaging self-contained Java applications.
+
+## Synopsis
+
+`jpackage` \[*options*\]
+
+
+*options*
+:   Command-line options separated by spaces. See [jpackage Options].
+
+## Description
+
+The `jpackage` tool will take as input a Java application and a Java run-time image, and produce a Java application image that includes all the necessary dependencies. It will be able to produce a native package in a platform-specific format, such as an exe on Windows or a dmg on macOS. Each format must be built on the platform it runs on, there is no cross-platform support. The tool will have options that allow packaged applications to be customized in various ways.
+
+
+## jpackage Options
+
+### Generic Options:
+
+`@`*filename*
+
+:   Read options from a file.
+
+    This option can be used multiple times.
+
+<a id="option-type">`--type` or `-t` *type*</a>
+:   The type of package to create
+
+    Valid values are: {"app-image", "exe", "msi", "rpm", "deb", "pkg", "dmg"}
+
+    If this option is not specified a platform dependent
+    default type will be created.
+
+<a id="option-app-version">`--app-version` *version*</a>
+
+:   Version of the application and/or package
+
+<a id="option-copyright">`--copyright` *copyright*</a>
+
+:   Copyright for the application
+
+<a id="option-description">`--description` *description*</a>
+
+:   Description of the application
+
+<a id="option-help">`--help` or `-h`</a>
+
+:   Print the usage text with a list and description of each valid
+    option for the current platform to the output stream, and exit.
+
+<a id="option-icon">`--icon` *path*</a>
+
+:   Path of the icon of the application package
+
+    (absolute path or relative to the current directory)
+
+<a id="option-name">`--name` or `-n` *name*</a>
+
+:   Name of the application and/or package
+
+<a id="option-dest">`--dest` or `-d` *destination*</a>
+
+:   Path where generated output file is placed
+
+    (absolute path or relative to the current directory).
+
+    Defaults to the current working directory.
+
+<a id="option-resource-dir">`--resource-dir` *path*</a>
+
+:   Path to override jpackage resources
+
+    (absolute path or relative to the current directory)
+
+    Icons, template files, and other resources of jpackage can be
+    over-ridden by adding replacement resources to this directory.
+
+<a id="option-temp">`--temp` *directory*</a>
+
+:   Path of a new or empty directory used to create temporary files
+
+    (absolute path or relative to the current directory)
+
+    If specified, the temp dir will not be removed upon the task
+    completion and must be removed manually.
+
+    If not specified, a temporary directory will be created and
+    removed upon the task completion.
+
+<a id="option-vendor">`--vendor` *vendor*</a>
+
+:   Vendor of the application
+
+<a id="option-verbose">`--verbose`</a>
+
+:   Enables verbose output.
+
+<a id="option-version">`--version`</a>
+
+:   Print the product version to the output stream and exit.
+
+### Options for creating the runtime image:
+
+
+<a id="option-add-modules">`--add-modules` *module-name* \[`,`*module-name*...\]</a>
+
+:   A comma (",") separated list of modules to add
+
+    This module list, along with the main module (if specified)
+    will be passed to jlink as the --add-module argument.
+    If not specified, either just the main module (if --module is
+    specified), or the default set of modules (if --main-jar is
+    specified) are used.
+
+    This option can be used multiple times.
+
+<a id="option-module-path">`--module-path` or `-p` *module-path* \[`,`*module-path*...\]</a>
+
+:   A File.pathSeparator separated list of paths
+
+    Each path is either a directory of modules or the path to a
+    modular jar, and is absolute or relative to the current directory.
+
+    This option can be used multiple times.
+
+<a id="option-jlink-options">`--jlink-options` *options*</a>
+
+:   A space separated list of options to pass to jlink
+
+    If not specified, defaults to "--strip-native-commands
+    --strip-debug --no-man-pages --no-header-files"
+
+    This option can be used multiple times.
+
+<a id="option-runtime-image">`--runtime-image` *directory*</a>
+
+:   Path of the predefined runtime image that will be copied into
+    the application image
+
+    (absolute path or relative to the current directory)
+
+    If --runtime-image is not specified, jpackage will run jlink to
+    create the runtime image using options specified by --jlink-options.
+
+### Options for creating the application image:
+
+<a id="option-input">`--input` or `-i` *directory*</a>
+
+:   Path of the input directory that contains the files to be packaged
+
+    (absolute path or relative to the current directory)
+
+    All files in the input directory will be packaged into the
+    application image.
+
+<a id="option-app-content">`--app-content` *additional-content* \[`,`*additional-content*...\]</a>
+
+:   A comma separated list of paths to files and/or directories
+    to add to the application payload.
+
+    This option can be used more than once.
+
+### Options for creating the application launcher(s):
+
+
+<a id="option-add-launcher">`--add-launcher` *name*=*path*</a>
+
+:   Name of launcher, and a path to a Properties file that contains
+    a list of key, value pairs
+
+    (absolute path or relative to the current directory)
+
+    The keys "module", "main-jar", "main-class", "description",
+    "arguments", "java-options", "icon", "launcher-as-service",
+    "win-console", "win-shortcut", "win-menu", and "linux-shortcut"
+    can be used.
+
+    These options are added to, or used to overwrite, the original
+    command line options to build an additional alternative launcher.
+    The main application launcher will be built from the command line
+    options. Additional alternative launchers can be built using
+    this option, and this option can be used multiple times to
+    build multiple additional launchers.
+
+<a id="option-arguments">`--arguments` *arguments*</a>
+
+:   Command line arguments to pass to the main class if no command
+    line arguments are given to the launcher
+
+    This option can be used multiple times.
+
+<a id="option-java-options">`--java-options` *options*</a>
+
+:   Options to pass to the Java runtime
+
+    This option can be used multiple times.
+
+<a id="option-main-class">`--main-class` *class-name*</a>
+
+:   Qualified name of the application main class to execute
+
+    This option can only be used if --main-jar is specified.
+
+<a id="option-main-jar">`--main-jar` *main-jar*</a>
+
+:   The main JAR of the application; containing the main class
+    (specified as a path relative to the input path)
+
+    Either --module or --main-jar option can be specified but not
+    both.
+
+<a id="option-module">`--module` or `-m` *module-name*[/*main-class*]</a>
+
+:   The main module (and optionally main class) of the application
+
+    This module must be located on the module path.
+
+    When this option is specified, the main module will be linked
+    in the Java runtime image.  Either --module or --main-jar
+    option can be specified but not both.
+
+
+### Platform dependent options for creating the application launcher:
+
+
+#### Windows platform options (available only when running on Windows):
+
+<a id="option-win-console">`--win-console`</a>
+
+:   Creates a console launcher for the application, should be
+    specified for application which requires console interactions
+
+#### macOS platform options (available only when running on macOS):
+
+<a id="option-mac-package-identifier">`--mac-package-identifier` *identifier*</a>
+
+:   An identifier that uniquely identifies the application for macOS
+
+    Defaults to the main class name.
+
+    May only use alphanumeric (A-Z,a-z,0-9), hyphen (-),
+    and period (.) characters.
+
+<a id="option-mac-package-name">`--mac-package-name` *name*</a>
+
+:   Name of the application as it appears in the Menu Bar
+
+    This can be different from the application name.
+
+    This name must be less than 16 characters long and be suitable for
+    displaying in the menu bar and the application Info window.
+    Defaults to the application name.
+
+<a id="option-mac-package-signing-prefix">`--mac-package-signing-prefix` *prefix*</a>
+
+:   When signing the application package, this value is prefixed to all
+    components that need to be signed that don't have
+    an existing package identifier.
+
+<a id="option-mac-sign">`--mac-sign`</a>
+
+:   Request that the package or the predefined application image be signed.
+
+<a id="option-mac-signing-keychain">`--mac-signing-keychain` *keychain-name*</a>
+
+:   Name of the keychain to search for the signing identity
+
+    If not specified, the standard keychains are used.
+
+<a id="option-mac-signing-key-user-name">`--mac-signing-key-user-name` *name*</a>
+
+:   Team or user name portion in Apple signing identities
+
+<a id="option-mac-app-store">`--mac-app-store`</a>
+
+:   Indicates that the jpackage output is intended for the Mac App Store.
+
+<a id="option-mac-entitlements">`--mac-entitlements` *path*</a>
+
+:   Path to file containing entitlements to use when signing executables and libraries in the bundle
+
+<a id="option-mac-app-category">`--mac-app-category` *category*</a>
+
+:   String used to construct LSApplicationCategoryType in application plist
+
+    The default value is "utilities".
+
+### Options for creating the application package:
+
+<a id="option-about-url">`--about-url` *url*</a>
+
+:   URL of the application's home page
+
+<a id="option-app-image">`--app-image` *directory*</a>
+
+:   Location of the predefined application image that is used to build an installable package
+    (on all platforms) or to be signed (on macOS)
+
+    (absolute path or relative to the current directory)
+
+<a id="option-file-associations">`--file-associations` *path*</a>
+
+:   Path to a Properties file that contains list of key, value pairs
+
+    (absolute path or relative to the current directory)
+
+    The keys "extension", "mime-type", "icon", and "description"
+    can be used to describe the association.
+
+    This option can be used multiple times.
+
+<a id="option-install-dir">`--install-dir` *path*</a>
+
+:   Absolute path of the installation directory of the application (on macOS
+    or linux), or relative sub-path of the installation directory
+    such as "Program Files" or "AppData" (on Windows)
+
+<a id="option-license-file">`--license-file` *path*</a>
+
+:   Path to the license file
+
+    (absolute path or relative to the current directory)
+
+<a id="option-application-package-runtime-image">`--runtime-image` *path*</a>
+
+:   Path of the predefined runtime image to install
+
+    (absolute path or relative to the current directory)
+
+    Option is required when creating a runtime installer.
+
+<a id="option-launcher-as-service">`--launcher-as-service`</a>
+
+:   Request to create an installer that will register the main
+    application launcher as a background service-type application.
+
+
+### Platform dependent options for creating the application package:
+
+
+#### Windows platform options (available only when running on Windows):
+
+<a id="option-win-dir-chooser">`--win-dir-chooser`</a>
+
+:   Adds a dialog to enable the user to choose a directory in which
+    the product is installed.
+
+<a id="option-win-help-url">`--win-help-url` *url*</a>
+
+:   URL where user can obtain further information or technical support
+
+<a id="option-win-menu">`--win-menu`</a>
+
+:   Request to add a Start Menu shortcut for this application
+
+<a id="option-win-menu-group">`--win-menu-group` *menu-group-name*</a>
+
+:   Start Menu group this application is placed in
+
+<a id="option-win-per-user-install">`--win-per-user-install`</a>
+
+:   Request to perform an install on a per-user basis
+
+<a id="option-win-shortcut">`--win-shortcut`</a>
+
+:   Request to create a desktop shortcut for this application
+
+<a id="option-win-shortcut-prompt">`--win-shortcut-prompt`</a>
+
+:   Adds a dialog to enable the user to choose if shortcuts will be created by installer
+
+<a id="option-win-update-url">`--win-update-url` *url*</a>
+
+:   URL of available application update information
+
+<a id="option-win-upgrade-uuid">`--win-upgrade-uuid` *id*</a>
+
+:   UUID associated with upgrades for this package
+
+#### Linux platform options (available only when running on Linux):
+
+<a id="option-linux-package-name">`--linux-package-name` *name*</a>
+
+:   Name for Linux package
+
+    Defaults to the application name.
+
+<a id="option-linux-deb-maintainer">`--linux-deb-maintainer` *email-address*</a>
+
+:   Maintainer for .deb bundle
+
+<a id="option-linux-menu-group">`--linux-menu-group` *menu-group-name*</a>
+
+:   Menu group this application is placed in
+
+<a id="option-linux-package-deps">`--linux-package-deps`</a>
+
+:   Required packages or capabilities for the application
+
+<a id="option-linux-rpm-license-type">`--linux-rpm-license-type` *type*</a>
+
+:   Type of the license ("License: *value*" of the RPM .spec)
+
+<a id="option-linux-app-release">`--linux-app-release` *release*</a>
+
+:   Release value of the RPM \<name\>.spec file or
+    Debian revision value of the DEB control file
+
+<a id="option-linux-app-category">`--linux-app-category` *category-value*</a>
+
+:   Group value of the RPM /<name/>.spec file or
+    Section value of DEB control file
+
+<a id="option-linux-shortcut">`--linux-shortcut`</a>
+
+:   Creates a shortcut for the application.
+
+#### macOS platform options (available only when running on macOS):
+
+<a id="option-mac-dmg-content">`--mac-dmg-content` *additional-content* \[`,`*additional-content*...\]</a>
+
+:   Include all the referenced content in the dmg.
+
+    This option can be used more than once.
+
+## jpackage Examples
+
+```
+Generate an application package suitable for the host system:
+```
+    For a modular application:
+        jpackage -n name -p modulePath -m moduleName/className
+    For a non-modular application:
+        jpackage -i inputDir -n name \
+            --main-class className --main-jar myJar.jar
+    From a pre-built application image:
+        jpackage -n name --app-image appImageDir
+
+```
+Generate an application image:
+```
+    For a modular application:
+        jpackage --type app-image -n name -p modulePath \
+            -m moduleName/className
+    For a non-modular application:
+        jpackage --type app-image -i inputDir -n name \
+            --main-class className --main-jar myJar.jar
+    To provide your own options to jlink, run jlink separately:
+        jlink --output appRuntimeImage -p modulePath \
+            --add-modules moduleName \
+            --no-header-files [<additional jlink options>...]
+        jpackage --type app-image -n name \
+            -m moduleName/className --runtime-image appRuntimeImage
+
+```
+Generate a Java runtime package:
+```
+    jpackage -n name --runtime-image <runtime-image>
+
+```
+Sign the predefined application image (on macOS):
+```
+    jpackage --type app-image --app-image <app-image> \
+        --mac-sign [<additional signing options>...]
+
+    Note: the only additional options that are permitted in this mode are:
+          the set of additional mac signing options and --verbose
+
+
+## jpackage resource directory
+
+Icons, template files, and other resources of jpackage can be over-ridden by
+adding replacement resources to this directory.
+jpackage will lookup files by specific names in the resource directory.
+
+
+### Resource directory files considered only when running on Linux:
+
+`<launcher-name>.png`
+
+:   Application launcher icon
+
+    Default resource is *JavaApp.png*
+
+`<launcher-name>.desktop`
+
+:   A desktop file to be used with `xdg-desktop-menu` command
+
+    Considered with application launchers registered for file associations and/or have an icon
+
+    Default resource is *template.desktop*
+
+
+#### Resource directory files considered only when building Linux DEB/RPM installer:
+
+`<package-name>-<launcher-name>.service`
+
+:   systemd unit file for application launcher registered as a background service-type application
+
+    Default resource is *unit-template.service*
+
+
+#### Resource directory files considered only when building Linux RPM installer:
+
+`<package-name>.spec`
+
+:   RPM spec file
+
+    Default resource is *template.spec*
+
+
+#### Resource directory files considered only when building Linux DEB installer:
+
+`control`
+
+:   Control file
+
+    Default resource is *template.control*
+
+`copyright`
+
+:   Copyright file
+
+    Default resource is *template.copyright*
+
+`preinstall`
+
+:   Pre-install shell script
+
+    Default resource is *template.preinstall*
+
+`prerm`
+
+:   Pre-remove shell script
+
+    Default resource is *template.prerm*
+
+`postinstall`
+
+:   Post-install shell script
+
+    Default resource is *template.postinstall*
+
+`postrm`
+
+:   Post-remove shell script
+
+    Default resource is *template.postrm*
+
+
+### Resource directory files considered only when running on Windows:
+
+`<launcher-name>.ico`
+
+:   Application launcher icon
+
+    Default resource is *JavaApp.ico*
+
+`<launcher-name>.properties`
+
+:   Properties file for application launcher executable
+
+    Default resource is *WinLauncher.template*
+
+
+#### Resource directory files considered only when building Windows MSI/EXE installer:
+
+`<application-name>-post-image.wsf`
+
+:   A Windows Script File (WSF) to run after building application image
+
+`main.wxs`
+
+:   Main WiX project file
+
+    Default resource is *main.wxs*
+
+`overrides.wxi`
+
+:   Overrides WiX project file
+
+    Default resource is *overrides.wxi*
+
+`service-installer.exe`
+
+:   Service installer executable
+
+    Considered if some application launchers are registered as background service-type applications
+
+`<launcher-name>-service-install.wxi`
+
+:   Service installer WiX project file
+
+    Considered if some application launchers are registered as background service-type applications
+
+    Default resource is *service-install.wxi*
+
+`<launcher-name>-service-config.wxi`
+
+:   Service installer WiX project file
+
+    Considered if some application launchers are registered as background service-type applications
+
+    Default resource is *service-config.wxi*
+
+`InstallDirNotEmptyDlg.wxs`
+
+:   WiX project file for installer UI dialog checking installation directory doesn't exist or is empty
+
+    Default resource is *InstallDirNotEmptyDlg.wxs*
+
+`ShortcutPromptDlg.wxs`
+
+:   WiX project file for installer UI dialog configuring shortcuts
+
+    Default resource is *ShortcutPromptDlg.wxs*
+
+`bundle.wxf`
+
+:   WiX project file with the hierarchy of components of application image
+
+`ui.wxf`
+
+:   WiX project file for installer UI
+
+
+#### Resource directory files considered only when building Windows EXE installer:
+
+`WinInstaller.properties`
+
+:   Properties file for the installer executable
+
+    Default resource is *WinInstaller.template*
+
+`<package-name>-post-msi.wsf`
+
+:   A Windows Script File (WSF) to run after building embedded MSI installer for EXE installer
+
+
+### Resource directory files considered only when running on macOS:
+
+`<launcher-name>.icns`
+
+:   Application launcher icon
+
+    Default resource is *JavaApp.icns*
+
+`Info.plist`
+
+:   Application property list file
+
+    Default resource is *Info-lite.plist.template*
+
+`Runtime-Info.plist`
+
+:   Java Runtime property list file
+
+    Default resource is *Runtime-Info.plist.template*
+
+`<application-name>.entitlements`
+
+:   Signing entitlements property list file
+
+    Default resource is *sandbox.plist*
+
+
+#### Resource directory files considered only when building macOS PKG/DMG installer:
+
+`<package-name>-post-image.sh`
+
+:   Shell script to run after building application image
+
+
+#### Resource directory files considered only when building macOS PKG installer:
+
+`uninstaller`
+
+:   Uninstaller shell script
+
+    Considered if some application launchers are registered as background service-type applications
+
+    Default resource is *uninstall.command.template*
+
+`preinstall`
+
+:   Pre-install shell script
+
+    Default resource is *preinstall.template*
+
+`postinstall`
+
+:   Post-install shell script
+
+    Default resource is *postinstall.template*
+
+`services-preinstall`
+
+:   Pre-install shell script for services package
+
+    Considered if some application launchers are registered as background service-type applications
+
+    Default resource is *services-preinstall.template*
+
+`services-postinstall`
+
+:   Post-install shell script for services package
+
+    Considered if some application launchers are registered as background service-type applications
+
+    Default resource is *services-postinstall.template*
+
+`<package-name>-background.png`
+
+:   Background image
+
+    Default resource is *background_pkg.png*
+
+`<package-name>-background-darkAqua.png`
+
+:   Dark background image
+
+    Default resource is *background_pkg.png*
+
+`product-def.plist`
+
+:   Package property list file
+
+    Default resource is *product-def.plist*
+
+`<package-name>-<launcher-name>.plist`
+
+:   launchd property list file for application launcher registered as a background service-type application
+
+    Default resource is *launchd.plist.template*
+
+
+#### Resource directory files considered only when building macOS DMG installer:
+
+`<package-name>-dmg-setup.scpt`
+
+:   Setup AppleScript script
+
+    Default resource is *DMGsetup.scpt*
+
+`<package-name>-license.plist`
+
+:   License property list file
+
+    Default resource is *lic_template.plist*
+
+`<package-name>-background.tiff`
+
+:   Background image
+
+    Default resource is *background_dmg.tiff*
+
+`<package-name>-volume.icns`
+
+:   Volume icon
+
+    Default resource is *JavaApp.icns*
diff --git a/src/jdk.jshell/share/man/jshell.1 b/src/jdk.jshell/share/man/jshell.1
deleted file mode 100644
index 6f478e57442..00000000000
--- a/src/jdk.jshell/share/man/jshell.1
+++ /dev/null
@@ -1,1292 +0,0 @@
-.\" Copyright (c) 2017, 2023, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.
-.\"
-'\" t
-.\" Automatically generated by Pandoc 2.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JSHELL" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jshell - interactively evaluate declarations, statements, and
-expressions of the Java programming language in a read-eval-print loop
-(REPL)
-.SH SYNOPSIS
-.PP
-\f[V]jshell\f[R] [\f[I]options\f[R]] [\f[I]load-files\f[R]]
-.TP
-\f[I]options\f[R]
-Command-line options, separated by spaces.
-See \f[B]Options for jshell\f[R].
-.TP
-\f[I]load-files\f[R]
-One or more scripts to run when the tool is started.
-Scripts can contain any valid code snippets or JShell commands.
-.RS
-.PP
-The script can be a local file or one of following predefined scripts:
-.TP
-\f[V]DEFAULT\f[R]
-Loads the default entries, which are commonly used as imports.
-.TP
-\f[V]JAVASE\f[R]
-Imports all Java SE packages.
-.TP
-\f[V]PRINTING\f[R]
-Defines \f[V]print\f[R], \f[V]println\f[R], and \f[V]printf\f[R] as
-\f[V]jshell\f[R] methods for use within the tool.
-.TP
-\f[V]TOOLING\f[R]
-Defines \f[V]javac\f[R], \f[V]jar\f[R], and other methods for running
-JDK tools via their command-line interface within the \f[V]jshell\f[R]
-tool.
-.PP
-For more than one script, use a space to separate the names.
-Scripts are run in the order in which they\[aq]re entered on the command
-line.
-Command-line scripts are run after startup scripts.
-To run a script after JShell is started, use the \f[V]/open\f[R]
-command.
-.PP
-To accept input from standard input and suppress the interactive I/O,
-enter a hyphen (-) for \f[I]load-files\f[R].
-This option enables the use of the \f[V]jshell\f[R] tool in pipe chains.
-.RE
-.SH DESCRIPTION
-.PP
-JShell provides a way to interactively evaluate declarations,
-statements, and expressions of the Java programming language, making it
-easier to learn the language, explore unfamiliar code and APIs, and
-prototype complex code.
-Java statements, variable definitions, method definitions, class
-definitions, import statements, and expressions are accepted.
-The bits of code entered are called snippets.
-.PP
-As snippets are entered, they\[aq]re evaluated, and feedback is
-provided.
-Feedback varies from the results and explanations of actions to nothing,
-depending on the snippet entered and the feedback mode chosen.
-Errors are described regardless of the feedback mode.
-Start with the verbose mode to get the most feedback while learning the
-tool.
-.PP
-Command-line options are available for configuring the initial
-environment when JShell is started.
-Within JShell, commands are available for modifying the environment as
-needed.
-.PP
-Existing snippets can be loaded from a file to initialize a JShell
-session, or at any time within a session.
-Snippets can be modified within the session to try out different
-variations and make corrections.
-To keep snippets for later use, save them to a file.
-.SH OPTIONS FOR JSHELL
-.TP
-\f[V]--add-exports\f[R] \f[I]module\f[R]/\f[I]package\f[R]
-Specifies a package to be considered as exported from its defining
-module.
-.TP
-\f[V]--add-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...]
-Specifies the root modules to resolve in addition to the initial module.
-.TP
-\f[V]-C\f[R]\f[I]flag\f[R]
-passes \f[I]flag\f[R] to the Java compiler inside JShell.
-For example, \f[V]-C-Xlint\f[R] enables all the recommended lint
-warnings, and \f[V]-C--release=<N>\f[R] compiles for Java SE N, as if
---release N was specified.
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies the directories and archives that are searched to locate class
-files.
-This option overrides the path in the \f[V]CLASSPATH\f[R] environment
-variable.
-If the environment variable isn\[aq]t set and this option isn\[aq]t
-used, then the current directory is searched.
-For Linux and macOS, use a colon (:) to separate items in the path.
-For Windows, use a semicolon (;) to separate items.
-.TP
-\f[V]--enable-preview\f[R]
-Allows code to depend on the preview features of this release.
-.TP
-\f[V]--execution\f[R] \f[I]specification\f[R]
-Specifies an alternate execution engine, where \f[I]specification\f[R]
-is an ExecutionControl spec.
-See the documentation of the package jdk.jshell.spi for the syntax of
-the spec.
-.TP
-\f[V]--feedback\f[R] \f[I]mode\f[R]
-Sets the initial level of feedback provided in response to what\[aq]s
-entered.
-The initial level can be overridden within a session by using the
-\f[V]/set feedback\f[R] \f[I]mode\f[R] command.
-The default is \f[V]normal\f[R].
-.RS
-.PP
-The following values are valid for \f[I]mode\f[R]:
-.TP
-\f[V]verbose\f[R]
-Provides detailed feedback for entries.
-Additional information about the action performed is displayed after the
-result of the action.
-The next prompt is separated from the feedback by a blank line.
-.TP
-\f[V]normal\f[R]
-Provides an average amount of feedback.
-The next prompt is separated from the feedback by a blank line.
-.TP
-\f[V]concise\f[R]
-Provides minimal feedback.
-The next prompt immediately follows the code snippet or feedback.
-.TP
-\f[V]silent\f[R]
-Provides no feedback.
-The next prompt immediately follows the code snippet.
-.TP
-\f[I]custom\f[R]
-Provides custom feedback based on how the mode is defined.
-Custom feedback modes are created within JShell by using the
-\f[V]/set mode\f[R] command.
-.RE
-.TP
-\f[V]--help\f[R] or \f[V]-h\f[R] or \f[V]-?\f[R]
-Prints a summary of standard options and exits the tool.
-.TP
-\f[V]--help-extra\f[R] or \f[V]-X\f[R]
-Prints a summary of nonstandard options and exits the tool.
-Nonstandard options are subject to change without notice.
-.TP
-\f[V]-J\f[R]\f[I]flag\f[R]
-passes \f[I]flag\f[R] to the runtime system, but has no effect on the
-execution of code snippets.
-To specify flags that affect the execution of code snippets, use
-\f[V]-R\f[R]\f[I]flag\f[R].
-Alternatively, use \f[V]-J\f[R]\f[I]flag\f[R] with
-\f[V]--execution local\f[R].
-.TP
-\f[V]--module-path\f[R] \f[I]modulepath\f[R]
-Specifies where to find application modules.
-For Linux and macOS, use a colon (:) to separate items in the path.
-For Windows, use a semicolon (;) to separate items.
-.TP
-\f[V]--no-startup\f[R]
-Prevents startup scripts from running when JShell starts.
-Use this option to run only the scripts entered on the command line when
-JShell is started, or to start JShell without any preloaded information
-if no scripts are entered.
-This option can\[aq]t be used if the \f[V]--startup\f[R] option is used.
-.TP
-\f[V]-q\f[R]
-Sets the feedback mode to \f[V]concise\f[R], which is the same as
-entering \f[V]--feedback concise\f[R].
-.TP
-\f[V]-R\f[R]\f[I]flag\f[R]
-passes \f[I]flag\f[R] to the runtime system only when code snippets are
-executed.
-For example, \f[V]-R-Dfoo=bar\f[R] means that execution of the snippet
-\f[V]System.getProperty(\[dq]foo\[dq])\f[R] will return
-\f[V]\[dq]bar\[dq]\f[R].
-.TP
-\f[V]-s\f[R]
-Sets the feedback mode to \f[V]silent\f[R], which is the same as
-entering \f[V]--feedback silent\f[R].
-.TP
-\f[V]--show-version\f[R]
-Prints version information and enters the tool.
-.TP
-\f[V]--startup\f[R] \f[I]file\f[R]
-Overrides the default startup script for this session.
-The script can contain any valid code snippets or commands.
-.RS
-.PP
-The script can be a local file or one of the following predefined
-scripts:
-.TP
-\f[V]DEFAULT\f[R]
-Loads the default entries, which are commonly used as imports.
-.TP
-\f[V]JAVASE\f[R]
-Imports all Java SE packages.
-.TP
-\f[V]PRINTING\f[R]
-Defines \f[V]print\f[R], \f[V]println\f[R], and \f[V]printf\f[R] as
-\f[V]jshell\f[R] methods for use within the tool.
-.TP
-\f[V]TOOLING\f[R]
-Defines \f[V]javac\f[R], \f[V]jar\f[R], and other methods for running
-JDK tools via their command-line interface within the \f[V]jshell\f[R]
-tool.
-.PP
-For more than one script, provide a separate instance of this option for
-each script.
-Startup scripts are run when JShell is first started and when the
-session is restarted with the \f[V]/reset\f[R], \f[V]/reload\f[R], or
-\f[V]/env\f[R] command.
-Startup scripts are run in the order in which they\[aq]re entered on the
-command line.
-.PP
-This option can\[aq]t be used if the \f[V]--no-startup\f[R] option is
-used.
-.RE
-.TP
-\f[V]-v\f[R]
-Sets the feedback mode to \f[V]verbose\f[R], which is the same as
-entering \f[V]--feedback verbose\f[R].
-.TP
-\f[V]--version\f[R]
-Prints version information and exits the tool.
-.SH JSHELL COMMANDS
-.PP
-Within the \f[V]jshell\f[R] tool, commands are used to modify the
-environment and manage code snippets.
-.TP
-\f[V]/drop\f[R] {\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Drops snippets identified by name, ID, or ID range, making them
-inactive.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of code snippets.
-.TP
-\f[V]/edit\f[R] [\f[I]option\f[R]]
-Opens an editor.
-If no option is entered, then the editor opens with the active snippets.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Opens the editor with the snippets identified by name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of code snippets.
-.TP
-\f[V]-all\f[R]
-Opens the editor with all snippets, including startup snippets and
-snippets that failed, were overwritten, or were dropped.
-.TP
-\f[V]-start\f[R]
-Opens the editor with startup snippets that were evaluated when JShell
-was started.
-.PP
-To exit edit mode, close the editor window, or respond to the prompt
-provided if the \f[V]-wait\f[R] option was used when the editor was set.
-.PP
-Use the \f[V]/set editor\f[R] command to specify the editor to use.
-If no editor is set, then the following environment variables are
-checked in order: \f[V]JSHELLEDITOR\f[R], \f[V]VISUAL\f[R], and
-\f[V]EDITOR\f[R].
-If no editor is set in JShell and none of the editor environment
-variables is set, then a simple default editor is used.
-.RE
-.TP
-\f[V]/env\f[R] [\f[I]options\f[R]]
-Displays the environment settings, or updates the environment settings
-and restarts the session.
-If no option is entered, then the current environment settings are
-displayed.
-If one or more options are entered, then the session is restarted as
-follows:
-.RS
-.IP \[bu] 2
-Updates the environment settings with the provided options.
-.IP \[bu] 2
-Resets the execution state.
-.IP \[bu] 2
-Runs the startup scripts.
-.IP \[bu] 2
-Silently replays the history in the order entered.
-The history includes all valid snippets or \f[V]/drop\f[R] commands
-entered at the \f[V]jshell\f[R] prompt, in scripts entered on the
-command line, or scripts entered with the \f[V]/open\f[R] command.
-.PP
-Environment settings entered on the command line or provided with a
-previous \f[V]/reset\f[R], \f[V]/env\f[R], or \f[V]/reload\f[R] command
-are maintained unless an \f[I]option\f[R] is entered that overwrites the
-setting.
-.PP
-The following options are valid:
-.TP
-\f[V]--add-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...]
-Specifies the root modules to resolve in addition to the initial module.
-.TP
-\f[V]--add-exports\f[R] \f[I]source-module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]target-module\f[R][\f[V],\f[R]\f[I]target-module\f[R]]*
-Adds an export of \f[I]package\f[R] from \f[I]source-module\f[R] to
-\f[I]target-module\f[R].
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies the directories and archives that are searched to locate class
-files.
-This option overrides the path in the \f[V]CLASSPATH\f[R] environment
-variable.
-If the environment variable isn\[aq]t set and this option isn\[aq]t
-used, then the current directory is searched.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.TP
-\f[V]--module-path\f[R] \f[I]modulepath\f[R]
-Specifies where to find application modules.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.RE
-.TP
-\f[V]/exit\f[R] [\f[I]integer-expression-snippet\f[R]]
-Exits the tool.
-If no snippet is entered, the exit status is zero.
-If a snippet is entered and the result of the snippet is an integer, the
-result is used as the exit status.
-If an error occurs, or the result of the snippet is not an integer, an
-error is displayed and the tool remains active.
-.TP
-\f[V]/history\f[R]
-Displays what was entered in this session.
-.TP
-\f[V]/help\f[R] [\f[I]command\f[R]|\f[I]subject\f[R]]
-Displays information about commands and subjects.
-If no options are entered, then a summary of information for all
-commands and a list of available subjects are displayed.
-If a valid command is provided, then expanded information for that
-command is displayed.
-If a valid subject is entered, then information about that subject is
-displayed.
-.RS
-.PP
-The following values for \f[I]subject\f[R] are valid:
-.TP
-\f[V]context\f[R]
-Describes the options that are available for configuring the
-environment.
-.TP
-\f[V]intro\f[R]
-Provides an introduction to the tool.
-.TP
-\f[V]shortcuts\f[R]
-Describes keystrokes for completing commands and snippets.
-See \f[B]Input Shortcuts\f[R].
-.RE
-.TP
-\f[V]/imports\f[R]
-Displays the current active imports, including those from the startup
-scripts and scripts that were entered on the command line when JShell
-was started.
-.TP
-\f[V]/list\f[R] [\f[I]option\f[R]]
-Displays a list of snippets and their IDs.
-If no option is entered, then all active snippets are displayed, but
-startup snippets aren\[aq]t.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Displays the snippets identified by name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-.TP
-\f[V]-all\f[R]
-Displays all snippets, including startup snippets and snippets that
-failed, were overwritten, or were dropped.
-IDs that begin with \f[V]s\f[R] are startup snippets.
-IDs that begin with \f[V]e\f[R] are snippets that failed.
-.TP
-\f[V]-start\f[R]
-Displays startup snippets that were evaluated when JShell was started.
-.RE
-.TP
-\f[V]/methods\f[R] [\f[I]option\f[R]]
-Displays information about the methods that were entered.
-If no option is entered, then the name, parameter types, and return type
-of all active methods are displayed.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Displays information for methods identified by name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of code snippets.
-.TP
-\f[V]-all\f[R]
-Displays information for all methods, including those added when JShell
-was started, and methods that failed, were overwritten, or were dropped.
-.TP
-\f[V]-start\f[R]
-Displays information for startup methods that were added when JShell was
-started.
-.RE
-.TP
-\f[V]/open\f[R] \f[I]file\f[R]
-Opens the script specified and reads the snippets into the tool.
-The script can be a local file or one of the following predefined
-scripts:
-.RS
-.TP
-\f[V]DEFAULT\f[R]
-Loads the default entries, which are commonly used as imports.
-.TP
-\f[V]JAVASE\f[R]
-Imports all Java SE packages.
-.TP
-\f[V]PRINTING\f[R]
-Defines \f[V]print\f[R], \f[V]println\f[R], and \f[V]printf\f[R] as
-\f[V]jshell\f[R] methods for use within the tool.
-.TP
-\f[V]TOOLING\f[R]
-Defines \f[V]javac\f[R], \f[V]jar\f[R], and other methods for running
-JDK tools via their command-line interface within the \f[V]jshell\f[R]
-tool.
-.RE
-.TP
-\f[V]/reload\f[R] [\f[I]options\f[R]]
-Restarts the session as follows:
-.RS
-.IP \[bu] 2
-Updates the environment settings with the provided options, if any.
-.IP \[bu] 2
-Resets the execution state.
-.IP \[bu] 2
-Runs the startup scripts.
-.IP \[bu] 2
-Replays the history in the order entered.
-The history includes all valid snippets or \f[V]/drop\f[R] commands
-entered at the \f[V]jshell\f[R] prompt, in scripts entered on the
-command line, or scripts entered with the \f[V]/open\f[R] command.
-.PP
-Environment settings entered on the command line or provided with a
-previous \f[V]/reset\f[R], \f[V]/env\f[R], or \f[V]/reload\f[R] command
-are maintained unless an \f[I]option\f[R] is entered that overwrites the
-setting.
-.PP
-The following options are valid:
-.TP
-\f[V]--add-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...]
-Specifies the root modules to resolve in addition to the initial module.
-.TP
-\f[V]--add-exports\f[R] \f[I]source-module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]target-module\f[R][\f[V],\f[R]\f[I]target-module\f[R]]*
-Adds an export of \f[I]package\f[R] from \f[I]source-module\f[R] to
-\f[I]target-module\f[R].
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies the directories and archives that are searched to locate class
-files.
-This option overrides the path in the \f[V]CLASSPATH\f[R] environment
-variable.
-If the environment variable isn\[aq]t set and this option isn\[aq]t
-used, then the current directory is searched.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.TP
-\f[V]--module-path\f[R] \f[I]modulepath\f[R]
-Specifies where to find application modules.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.TP
-\f[V]-quiet\f[R]
-Replays the valid history without displaying it.
-Errors are displayed.
-.TP
-\f[V]-restore\f[R]
-Resets the environment to the state at the start of the previous run of
-the tool or to the last time a \f[V]/reset\f[R], \f[V]/reload\f[R], or
-\f[V]/env\f[R] command was executed in the previous run.
-The valid history since that point is replayed.
-Use this option to restore a previous JShell session.
-.RE
-.TP
-\f[V]/reset\f[R] [\f[I]options\f[R]]
-Discards all entered snippets and restarts the session as follows:
-.RS
-.IP \[bu] 2
-Updates the environment settings with the provided options, if any.
-.IP \[bu] 2
-Resets the execution state.
-.IP \[bu] 2
-Runs the startup scripts.
-.PP
-History is not replayed.
-All code that was entered is lost.
-.PP
-Environment settings entered on the command line or provided with a
-previous \f[V]/reset\f[R], \f[V]/env\f[R], or \f[V]/reload\f[R] command
-are maintained unless an \f[I]option\f[R] is entered that overwrites the
-setting.
-.PP
-The following options are valid:
-.TP
-\f[V]--add-modules\f[R] \f[I]module\f[R][\f[V],\f[R]\f[I]module\f[R]...]
-Specifies the root modules to resolve in addition to the initial module.
-.TP
-\f[V]--add-exports\f[R] \f[I]source-module\f[R]\f[V]/\f[R]\f[I]package\f[R]\f[V]=\f[R]\f[I]target-module\f[R][\f[V],\f[R]\f[I]target-module\f[R]]*
-Adds an export of \f[I]package\f[R] from \f[I]source-module\f[R] to
-\f[I]target-module\f[R].
-.TP
-\f[V]--class-path\f[R] \f[I]path\f[R]
-Specifies the directories and archives that are searched to locate class
-files.
-This option overrides the path in the \f[V]CLASSPATH\f[R] environment
-variable.
-If the environment variable isn\[aq]t set and this option isn\[aq]t
-used, then the current directory is searched.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.TP
-\f[V]--module-path\f[R] \f[I]modulepath\f[R]
-Specifies where to find application modules.
-For Linux and macOS, use a colon (\f[V]:\f[R]) to separate items in the
-path.
-For Windows, use a semicolon (\f[V];\f[R]) to separate items.
-.RE
-.TP
-\f[V]/save\f[R] [\f[I]options\f[R]] \f[I]file\f[R]
-Saves snippets and commands to the file specified.
-If no options are entered, then active snippets are saved.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Saves the snippets and commands identified by name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of the code snippets.
-.TP
-\f[V]-all\f[R]
-Saves all snippets, including startup snippets and snippets that were
-overwritten or failed.
-.TP
-\f[V]-history\f[R]
-Saves the sequential history of all commands and snippets entered in the
-current session.
-.TP
-\f[V]-start\f[R]
-Saves the current startup settings.
-If no startup scripts were provided, then an empty file is saved.
-.RE
-.TP
-\f[V]/set\f[R] [\f[I]setting\f[R]]
-Sets configuration information, including the external editor, startup
-settings, and feedback mode.
-This command is also used to create a custom feedback mode with
-customized prompt, format, and truncation values.
-If no setting is entered, then the current setting for the editor,
-startup settings, and feedback mode are displayed.
-.RS
-.PP
-The following values are valid for \f[V]setting\f[R]:
-.TP
-\f[V]editor\f[R] [\f[I]options\f[R]] [\f[I]command\f[R]]
-Sets the command used to start an external editor when the
-\f[V]/edit\f[R] command is entered.
-The command can include command arguments separated by spaces.
-If no command or options are entered, then the current setting is
-displayed.
-.RS
-.PP
-The following options are valid:
-.TP
-\f[V]-default\f[R]
-Sets the editor to the default editor provided with JShell.
-This option can\[aq]t be used if a command for starting an editor is
-entered.
-.TP
-\f[V]-delete\f[R]
-Sets the editor to the one in effect when the session started.
-If used with the \f[V]-retain\f[R] option, then the retained editor
-setting is deleted and the editor is set to the first of the following
-environment variables found: \f[V]JSHELLEDITOR\f[R], \f[V]VISUAL\f[R],
-or \f[V]EDITOR\f[R].
-If none of the editor environment variables are set, then this option
-sets the editor to the default editor.
-.RS
-.PP
-This option can\[aq]t be used if a command for starting an editor is
-entered.
-.RE
-.TP
-\f[V]-retain\f[R]
-Saves the editor setting across sessions.
-If no other option or a command is entered, then the current setting is
-saved.
-.TP
-\f[V]-wait\f[R]
-Prompts the user to indicate when editing is complete.
-Otherwise control returns to JShell when the editor exits.
-Use this option if the editor being used exits immediately, for example,
-when an edit window already exists.
-This option is valid only when a command for starting an editor is
-entered.
-.RE
-.TP
-\f[V]feedback\f[R] [\f[I]mode\f[R]]
-Sets the feedback mode used to respond to input.
-If no mode is entered, then the current mode is displayed.
-.RS
-.PP
-The following modes are valid: \f[V]concise\f[R], \f[V]normal\f[R],
-\f[V]silent\f[R], \f[V]verbose\f[R], and any custom mode created with
-the \f[V]/set mode\f[R] command.
-.RE
-.TP
-\f[V]format\f[R] \f[I]mode\f[R] \f[I]field\f[R] \f[V]\[dq]\f[R]\f[I]format-string\f[R]\f[V]\[dq]\f[R] \f[I]selector\f[R]
-Sets the format of the feedback provided in response to input.
-If no mode is entered, then the current formats for all fields for all
-feedback modes are displayed.
-If only a mode is entered, then the current formats for that mode are
-displayed.
-If only a mode and field are entered, then the current formats for that
-field are displayed.
-.RS
-.PP
-To define a format, the following arguments are required:
-.TP
-\f[I]mode\f[R]
-Specifies a feedback mode to which the response format is applied.
-Only custom modes created with the \f[V]/set mode\f[R] command can be
-modified.
-.TP
-\f[I]field\f[R]
-Specifies a context-specific field to which the response format is
-applied.
-The fields are described in the online help, which is accessed from
-JShell using the \f[V]/help /set format\f[R] command.
-.TP
-\f[V]\[dq]\f[R]\f[I]format-string\f[R]\f[V]\[dq]\f[R]
-Specifies the string to use as the response format for the specified
-field and selector.
-The structure of the format string is described in the online help,
-which is accessed from JShell using the \f[V]/help /set format\f[R]
-command.
-.TP
-\f[I]selector\f[R]
-Specifies the context in which the response format is applied.
-The selectors are described in the online help, which is accessed from
-JShell using the \f[V]/help /set format\f[R] command.
-.RE
-.TP
-\f[V]mode\f[R] [\f[I]mode-name\f[R]] [\f[I]existing-mode\f[R]] [\f[I]options\f[R]]
-Creates a custom feedback mode with the mode name provided.
-If no mode name is entered, then the settings for all modes are
-displayed, which includes the mode, prompt, format, and truncation
-settings.
-If the name of an existing mode is provided, then the settings from the
-existing mode are copied to the mode being created.
-.RS
-.PP
-The following options are valid:
-.TP
-\f[V]-command\f[R]|\f[V]-quiet\f[R]
-Specifies the level of feedback displayed for commands when using the
-mode.
-This option is required when creating a feedback mode.
-Use \f[V]-command\f[R] to show information and verification feedback for
-commands.
-Use \f[V]-quiet\f[R] to show only essential feedback for commands, such
-as error messages.
-.TP
-\f[V]-delete\f[R]
-Deletes the named feedback mode for this session.
-The name of the mode to delete is required.
-To permanently delete a retained mode, use the \f[V]-retain\f[R] option
-with this option.
-Predefined modes can\[aq]t be deleted.
-.TP
-\f[V]-retain\f[R]
-Saves the named feedback mode across sessions.
-The name of the mode to retain is required.
-.PP
-Configure the new feedback mode using the \f[V]/set prompt\f[R],
-\f[V]/set format\f[R], and \f[V]/set truncation\f[R] commands.
-.PP
-To start using the new mode, use the \f[V]/set feedback\f[R] command.
-.RE
-.TP
-\f[V]prompt\f[R] \f[I]mode\f[R] \f[V]\[dq]\f[R]\f[I]prompt-string\f[R]\f[V]\[dq]\f[R] \f[V]\[dq]\f[R]\f[I]continuation-prompt-string\f[R]\f[V]\[dq]\f[R]
-Sets the prompts for input within JShell.
-If no mode is entered, then the current prompts for all feedback modes
-are displayed.
-If only a mode is entered, then the current prompts for that mode are
-displayed.
-.RS
-.PP
-To define a prompt, the following arguments are required:
-.TP
-\f[I]mode\f[R]
-Specifies the feedback mode to which the prompts are applied.
-Only custom modes created with the \f[V]/set mode\f[R] command can be
-modified.
-.TP
-\f[V]\[dq]\f[R]\f[I]prompt-string\f[R]\f[V]\[dq]\f[R]
-Specifies the string to use as the prompt for the first line of input.
-.TP
-\f[V]\[dq]\f[R]\f[I]continuation-prompt-string\f[R]\f[V]\[dq]\f[R]
-Specifies the string to use as the prompt for the additional input lines
-needed to complete a snippet.
-.RE
-.TP
-\f[V]start\f[R] [\f[V]-retain\f[R]] [\f[I]file\f[R] [\f[I]file\f[R]...]|\f[I]option\f[R]]
-Sets the names of the startup scripts used when the next
-\f[V]/reset\f[R], \f[V]/reload\f[R], or \f[V]/env\f[R] command is
-entered.
-If more than one script is entered, then the scripts are run in the
-order entered.
-If no scripts or options are entered, then the current startup settings
-are displayed.
-.RS
-.PP
-The scripts can be local files or one of the following predefined
-scripts:
-.TP
-\f[V]DEFAULT\f[R]
-Loads the default entries, which are commonly used as imports.
-.TP
-\f[V]JAVASE\f[R]
-Imports all Java SE packages.
-.TP
-\f[V]PRINTING\f[R]
-Defines \f[V]print\f[R], \f[V]println\f[R], and \f[V]printf\f[R] as
-\f[V]jshell\f[R] methods for use within the tool.
-.TP
-\f[V]TOOLING\f[R]
-Defines \f[V]javac\f[R], \f[V]jar\f[R], and other methods for running
-JDK tools via their command-line interface within the \f[V]jshell\f[R]
-tool.
-.PP
-The following options are valid:
-.TP
-\f[V]-default\f[R]
-Sets the startup settings to the default settings.
-.TP
-\f[V]-none\f[R]
-Specifies that no startup settings are used.
-.PP
-Use the \f[V]-retain\f[R] option to save the start setting across
-sessions.
-.RE
-.TP
-\f[V]truncation\f[R] \f[I]mode\f[R] \f[I]length\f[R] \f[I]selector\f[R]
-Sets the maximum length of a displayed value.
-If no mode is entered, then the current truncation values for all
-feedback modes are displayed.
-If only a mode is entered, then the current truncation values for that
-mode are displayed.
-.RS
-.PP
-To define truncation values, the following arguments are required:
-.TP
-\f[I]mode\f[R]
-Specifies the feedback mode to which the truncation value is applied.
-Only custom modes created with the \f[V]/set mode\f[R] command can be
-modified.
-.TP
-\f[I]length\f[R]
-Specifies the unsigned integer to use as the maximum length for the
-specified selector.
-.TP
-\f[I]selector\f[R]
-Specifies the context in which the truncation value is applied.
-The selectors are described in the online help, which is accessed from
-JShell using the \f[V]/help /set truncation\f[R] command.
-.RE
-.RE
-.TP
-\f[V]/types\f[R] [\f[I]option\f[R]]
-Displays classes, interfaces, and enums that were entered.
-If no option is entered, then all current active classes, interfaces,
-and enums are displayed.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Displays information for classes, interfaces, and enums identified by
-name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of the code snippets.
-.TP
-\f[V]-all\f[R]
-Displays information for all classes, interfaces, and enums, including
-those added when JShell was started, and classes, interfaces, and enums
-that failed, were overwritten, or were dropped.
-.TP
-\f[V]-start\f[R]
-Displays information for startup classes, interfaces, and enums that
-were added when JShell was started.
-.RE
-.TP
-\f[V]/vars\f[R] [\f[I]option\f[R]]
-Displays the name, type, and value of variables that were entered.
-If no option is entered, then all current active variables are
-displayed.
-.RS
-.PP
-The following options are valid:
-.TP
-{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Displays information for variables identified by name, ID, or ID range.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-Use the \f[V]/list\f[R] command to see the IDs of the code snippets.
-.TP
-\f[V]-all\f[R]
-Displays information for all variables, including those added when
-JShell was started, and variables that failed, were overwritten, or were
-dropped.
-.TP
-\f[V]-start\f[R]
-Displays information for startup variables that were added when JShell
-was started.
-.RE
-.TP
-\f[V]/?\f[R]
-Same as the \f[V]/help\f[R] command.
-.TP
-\f[V]/!\f[R]
-Reruns the last snippet.
-.TP
-\f[V]/\f[R]{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]} [{\f[I]name\f[R]|\f[I]id\f[R]|\f[I]startID\f[R]\f[V]-\f[R]\f[I]endID\f[R]}...]
-Reruns the snippets identified by ID, range of IDs, or name.
-For a range of IDs, provide the starting ID and ending ID separated with
-a hyphen.
-To provide a list, separate the items in the list with a space.
-The first item in the list must be an ID or ID range.
-Use the \f[V]/list\f[R] command to see the IDs of the code snippets.
-.TP
-\f[V]/-\f[R]\f[I]n\f[R]
-Reruns the -\f[I]n\f[R]th previous snippet.
-For example, if 15 code snippets were entered, then \f[V]/-4\f[R] runs
-the 11th snippet.
-Commands aren\[aq]t included in the count.
-.SH INPUT SHORTCUTS
-.PP
-The following shortcuts are available for entering commands and snippets
-in JShell.
-.SS Tab completion
-.TP
-\f[B]<tab>\f[R]
-When entering snippets, commands, subcommands, command arguments, or
-command options, use the Tab key to automatically complete the item.
-If the item can\[aq]t be determined from what was entered, then possible
-options are provided.
-.RS
-.PP
-When entering a method call, use the Tab key after the method call\[aq]s
-opening parenthesis to see the parameters for the method.
-If the method has more than one signature, then all signatures are
-displayed.
-Pressing the Tab key a second time displays the description of the
-method and the parameters for the first signature.
-Continue pressing the Tab key for a description of any additional
-signatures.
-.RE
-.TP
-\f[B]Shift+<Tab> V\f[R]
-After entering a complete expression, use this key sequence to convert
-the expression to a variable declaration of a type determined by the
-type of the expression.
-.TP
-\f[B]Shift+<Tab> M\f[R]
-After entering a complete expression or statement, use this key sequence
-to convert the expression or statement to a method declaration.
-If an expression is entered, the return type is based on the type of the
-expression.
-.TP
-\f[B]Shift+<Tab> I\f[R]
-When an identifier is entered that can\[aq]t be resolved, use this key
-sequence to show possible imports that resolve the identifier based on
-the content of the specified class path.
-.SS Command abbreviations
-.PP
-An abbreviation of a command is accepted if the abbreviation uniquely
-identifies a command.
-For example, \f[V]/l\f[R] is recognized as the \f[V]/list\f[R] command.
-However, \f[V]/s\f[R] isn\[aq]t a valid abbreviation because it
-can\[aq]t be determined if the \f[V]/set\f[R] or \f[V]/save\f[R] command
-is meant.
-Use \f[V]/se\f[R] for the \f[V]/set\f[R] command or \f[V]/sa\f[R] for
-the \f[V]/save\f[R] command.
-.PP
-Abbreviations are also accepted for subcommands, command arguments, and
-command options.
-For example, use \f[V]/m -a\f[R] to display all methods.
-.SS History navigation
-.PP
-A history of what was entered is maintained across sessions.
-Use the up and down arrows to scroll through commands and snippets from
-the current and past sessions.
-Use the Ctrl key with the up and down arrows to skip all but the first
-line of multiline snippets.
-.SS History search
-.PP
-Use the Ctrl+R key combination to search the history for the string
-entered.
-The prompt changes to show the string and the match.
-Ctrl+R searches backwards from the current location in the history
-through earlier entries.
-Ctrl+S searches forward from the current location in the history though
-later entries.
-.SH INPUT EDITING
-.PP
-The editing capabilities of JShell are similar to that of other common
-shells.
-Keyboard keys and key combinations provide line editing shortcuts.
-The Ctrl key and Meta key are used in key combinations.
-If your keyboard doesn\[aq]t have a Meta key, then the Alt key is often
-mapped to provide Meta key functionality.
-.PP
-Line Editing Shortcuts
-.TS
-tab(@);
-l l.
-T{
-Key or Key Combination
-T}@T{
-Action
-T}
-_
-T{
-Return
-T}@T{
-Enter the current line.
-T}
-T{
-Left arrow
-T}@T{
-Move the cursor to the left one character.
-T}
-T{
-Right arrow Move
-T}@T{
-the cursor to the right one character.
-T}
-T{
-Ctrl+A
-T}@T{
-Move the cursor to the beginning of the line.
-T}
-T{
-Ctrl+E
-T}@T{
-Move the cursor to the end of the line.
-T}
-T{
-Meta+B
-T}@T{
-Move the cursor to the left one word.
-T}
-T{
-Meta+F
-T}@T{
-Move the cursor to the right one word.
-T}
-T{
-Delete
-T}@T{
-Delete the character under the cursor.
-T}
-T{
-Backspace
-T}@T{
-Delete the character before the cursor.
-T}
-T{
-Ctrl+K
-T}@T{
-Delete the text from the cursor to the end of the line.
-T}
-T{
-Meta+D
-T}@T{
-Delete the text from the cursor to the end of the word.
-T}
-T{
-Ctrl+W
-T}@T{
-Delete the text from the cursor to the previous white space.
-T}
-T{
-Ctrl+Y
-T}@T{
-Paste the most recently deleted text into the line.
-T}
-T{
-Meta+Y
-T}@T{
-After Ctrl+Y, press to cycle through the previously deleted text.
-T}
-.TE
-.SH EXAMPLE OF STARTING AND STOPPING A JSHELL SESSION
-.PP
-JShell is provided with the JDK.
-To start a session, enter \f[V]jshell\f[R] on the command line.
-A welcome message is printed, and a prompt for entering commands and
-snippets is provided.
-.IP
-.nf
-\f[CB]
-% jshell
-|  Welcome to JShell -- Version 9
-|  For an introduction type: /help intro
-
-jshell>
-\f[R]
-.fi
-.PP
-To see which snippets were automatically loaded when JShell started, use
-the \f[V]/list -start\f[R] command.
-The default startup snippets are import statements for common packages.
-The ID for each snippet begins with the letter \f[I]s\f[R], which
-indicates it\[aq]s a startup snippet.
-.IP
-.nf
-\f[CB]
-jshell> /list -start
-
-  s1 : import java.io.*;
-  s2 : import java.math.*;
-  s3 : import java.net.*;
-  s4 : import java.nio.file.*;
-  s5 : import java.util.*;
-  s6 : import java.util.concurrent.*;
-  s7 : import java.util.function.*;
-  s8 : import java.util.prefs.*;
-  s9 : import java.util.regex.*;
- s10 : import java.util.stream.*;
-
-jshell>
-\f[R]
-.fi
-.PP
-To end the session, use the \f[V]/exit\f[R] command.
-.IP
-.nf
-\f[CB]
-jshell> /exit
-|  Goodbye
-
-%
-\f[R]
-.fi
-.SH EXAMPLE OF ENTERING SNIPPETS
-.PP
-Snippets are Java statements, variable definitions, method definitions,
-class definitions, import statements, and expressions.
-Terminating semicolons are automatically added to the end of a completed
-snippet if they\[aq]re missing.
-.PP
-The following example shows two variables and a method being defined,
-and the method being run.
-Note that a scratch variable is automatically created to hold the result
-because no variable was provided.
-.IP
-.nf
-\f[CB]
-jshell> int a=4
-a ==> 4
-
-jshell> int b=8
-b ==> 8
-
-jshell> int square(int i1) {
-   ...> return i1 * i1;
-   ...> }
-|  created method square(int)
-
-jshell> square(b)
-$5 ==> 64
-\f[R]
-.fi
-.SH EXAMPLE OF CHANGING SNIPPETS
-.PP
-Change the definition of a variable, method, or class by entering it
-again.
-.PP
-The following examples shows a method being defined and the method run:
-.IP
-.nf
-\f[CB]
-jshell> String grade(int testScore) {
-   ...>     if (testScore >= 90) {
-   ...>         return \[dq]Pass\[dq];
-   ...>     }
-   ...>     return \[dq]Fail\[dq];
-   ...> }
-|  created method grade(int)
-
-jshell> grade(88)
-$3 ==> \[dq]Fail\[dq]
-\f[R]
-.fi
-.PP
-To change the method \f[V]grade\f[R] to allow more students to pass,
-enter the method definition again and change the pass score to
-\f[V]80\f[R].
-Use the up arrow key to retrieve the previous entries to avoid having to
-reenter them and make the change in the \f[V]if\f[R] statement.
-The following example shows the new definition and reruns the method to
-show the new result:
-.IP
-.nf
-\f[CB]
-jshell> String grade(int testScore) {
-   ...>     if (testScore >= 80) {
-   ...>         return \[dq]Pass\[dq];
-   ...>     }
-   ...>     return \[dq]Fail\[dq];
-   ...> }
-|  modified method grade(int)
-
-jshell> grade(88)
-$5 ==> \[dq]Pass\[dq]
-\f[R]
-.fi
-.PP
-For snippets that are more than a few lines long, or to make more than a
-few changes, use the \f[V]/edit\f[R] command to open the snippet in an
-editor.
-After the changes are complete, close the edit window to return control
-to the JShell session.
-The following example shows the command and the feedback provided when
-the edit window is closed.
-The \f[V]/list\f[R] command is used to show that the pass score was
-changed to \f[V]85\f[R].
-.IP
-.nf
-\f[CB]
-jshell> /edit grade
-|  modified method grade(int)
-jshell> /list grade
-
-   6 : String grade(int testScore) {
-           if (testScore >= 85) {
-               return \[dq]Pass\[dq];
-           }
-           return \[dq]Fail\[dq];
-       }
-\f[R]
-.fi
-.SH EXAMPLE OF CREATING A CUSTOM FEEDBACK MODE
-.PP
-The feedback mode determines the prompt that\[aq]s displayed, the
-feedback messages that are provided as snippets are entered, and the
-maximum length of a displayed value.
-Predefined feedback modes are provided.
-Commands for creating custom feedback modes are also provided.
-.PP
-Use the \f[V]/set mode\f[R] command to create a new feedback mode.
-In the following example, the new mode \f[V]mymode\f[R], is based on the
-predefined feedback mode, \f[V]normal\f[R], and verifying command
-feedback is displayed:
-.IP
-.nf
-\f[CB]
-jshell> /set mode mymode normal -command
-|  Created new feedback mode: mymode
-\f[R]
-.fi
-.PP
-Because the new mode is based on the \f[V]normal\f[R] mode, the prompts
-are the same.
-The following example shows how to see what prompts are used and then
-changes the prompts to custom strings.
-The first string represents the standard JShell prompt.
-The second string represents the prompt for additional lines in
-multiline snippets.
-.IP
-.nf
-\f[CB]
-jshell> /set prompt mymode
-|  /set prompt mymode \[dq]\[rs]njshell> \[dq] \[dq]   ...> \[dq]
-
-jshell> /set prompt mymode \[dq]\[rs]nprompt$ \[dq] \[dq]   continue$ \[dq]
-\f[R]
-.fi
-.PP
-The maximum length of a displayed value is controlled by the truncation
-setting.
-Different types of values can have different lengths.
-The following example sets an overall truncation value of 72, and a
-truncation value of 500 for variable value expressions:
-.IP
-.nf
-\f[CB]
-jshell> /set truncation mymode 72
-
-jshell> /set truncation mymode 500 varvalue
-\f[R]
-.fi
-.PP
-The feedback displayed after snippets are entered is controlled by the
-format setting and is based on the type of snippet entered and the
-action taken for that snippet.
-In the predefined mode \f[V]normal\f[R], the string \f[V]created\f[R] is
-displayed when a method is created.
-The following example shows how to change that string to
-\f[V]defined\f[R]:
-.IP
-.nf
-\f[CB]
-jshell> /set format mymode action \[dq]defined\[dq] added-primary
-\f[R]
-.fi
-.PP
-Use the \f[V]/set feedback\f[R] command to start using the feedback mode
-that was just created.
-The following example shows the custom mode in use:
-.IP
-.nf
-\f[CB]
-jshell> /set feedback mymode
-|  Feedback mode: mymode
-
-prompt$ int square (int num1){
-   continue$ return num1*num1;
-   continue$ }
-|  defined method square(int)
-
-prompt$
-\f[R]
-.fi
diff --git a/src/jdk.jshell/share/man/jshell.md b/src/jdk.jshell/share/man/jshell.md
new file mode 100644
index 00000000000..b9f9fe577cf
--- /dev/null
+++ b/src/jdk.jshell/share/man/jshell.md
@@ -0,0 +1,1042 @@
+---
+# Copyright (c) 2017, 2023, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JSHELL(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jshell - interactively evaluate declarations, statements, and expressions of
+the Java programming language in a read-eval-print loop (REPL)
+
+## Synopsis
+
+`jshell` \[*options*\] \[*load-files*\]
+
+*options*
+:   Command-line options, separated by spaces. See [Options for jshell].
+
+*load-files*
+:   One or more scripts to run when the tool is started. Scripts can contain
+    any valid code snippets or JShell commands.
+
+    The script can be a local file or one of following predefined scripts:
+
+    `DEFAULT`
+    :   Loads the default entries, which are commonly used as imports.
+
+    `JAVASE`
+    :   Imports all Java SE packages.
+
+    `PRINTING`
+    :   Defines `print`, `println`, and `printf` as `jshell` methods for use
+        within the tool.
+
+    `TOOLING`
+    :   Defines `javac`, `jar`, and other methods for running JDK tools via
+        their command-line interface within the `jshell` tool.
+
+    For more than one script, use a space to separate the names. Scripts are
+    run in the order in which they're entered on the command line. Command-line
+    scripts are run after startup scripts. To run a script after JShell is
+    started, use the `/open` command.
+
+    To accept input from standard input and suppress the interactive I/O, enter
+    a hyphen (-) for *load-files*. This option enables the use of the `jshell`
+    tool in pipe chains.
+
+## Description
+
+JShell provides a way to interactively evaluate declarations, statements, and
+expressions of the Java programming language, making it easier to learn the
+language, explore unfamiliar code and APIs, and prototype complex code. Java
+statements, variable definitions, method definitions, class definitions, import
+statements, and expressions are accepted. The bits of code entered are called
+snippets.
+
+As snippets are entered, they're evaluated, and feedback is provided. Feedback
+varies from the results and explanations of actions to nothing, depending on
+the snippet entered and the feedback mode chosen. Errors are described
+regardless of the feedback mode. Start with the verbose mode to get the most
+feedback while learning the tool.
+
+Command-line options are available for configuring the initial environment when
+JShell is started. Within JShell, commands are available for modifying the
+environment as needed.
+
+Existing snippets can be loaded from a file to initialize a JShell session, or
+at any time within a session. Snippets can be modified within the session to
+try out different variations and make corrections. To keep snippets for later
+use, save them to a file.
+
+## Options for jshell
+
+`--add-exports` *module*/*package*
+:   Specifies a package to be considered as exported from its defining module.
+
+`--add-modules` *module*\[`,`*module*...\]
+:   Specifies the root modules to resolve in addition to the initial module.
+
+`-C`*flag*
+:   passes *flag* to the Java compiler inside JShell. For example, `-C-Xlint`
+    enables all the recommended lint warnings, and `-C--release=<N>` compiles
+    for Java SE N, as if --release N was specified.
+
+`--class-path` *path*
+:   Specifies the directories and archives that are searched to locate class
+    files. This option overrides the path in the `CLASSPATH` environment
+    variable. If the environment variable isn't set and this option isn't used,
+    then the current directory is searched. For Linux and macOS, use a colon
+    (:) to separate items in the path. For Windows, use a semicolon (;) to
+    separate items.
+
+`--enable-preview`
+:   Allows code to depend on the preview features of this release.
+
+`--execution` *specification*
+:   Specifies an alternate execution engine, where *specification* is an
+    ExecutionControl spec. See the documentation of the package jdk.jshell.spi
+    for the syntax of the spec.
+
+`--feedback` *mode*
+:   Sets the initial level of feedback provided in response to what's entered.
+    The initial level can be overridden within a session by using the
+    `/set feedback` *mode* command. The default is `normal`.
+
+    The following values are valid for *mode*:
+
+    `verbose`
+    :   Provides detailed feedback for entries. Additional information about
+        the action performed is displayed after the result of the action. The
+        next prompt is separated from the feedback by a blank line.
+
+    `normal`
+    :   Provides an average amount of feedback. The next prompt is separated
+        from the feedback by a blank line.
+
+    `concise`
+    :   Provides minimal feedback. The next prompt immediately follows the code
+        snippet or feedback.
+
+    `silent`
+    :   Provides no feedback. The next prompt immediately follows the code
+        snippet.
+
+    *custom*
+    :   Provides custom feedback based on how the mode is defined. Custom
+        feedback modes are created within JShell by using the `/set mode`
+        command.
+
+`--help` or `-h` or `-?`
+:   Prints a summary of standard options and exits the tool.
+
+`--help-extra` or `-X`
+:   Prints a summary of nonstandard options and exits the tool. Nonstandard
+    options are subject to change without notice.
+
+`-J`*flag*
+:   passes *flag* to the runtime system, but has no effect on the execution of
+    code snippets. To specify flags that affect the execution of code snippets,
+    use `-R`*flag*. Alternatively, use `-J`*flag* with `--execution local`.
+
+`--module-path` *modulepath*
+:   Specifies where to find application modules. For Linux and macOS, use a
+    colon (:) to separate items in the path. For Windows, use a semicolon (;)
+    to separate items.
+
+`--no-startup`
+:   Prevents startup scripts from running when JShell starts. Use this option
+    to run only the scripts entered on the command line when JShell is started,
+    or to start JShell without any preloaded information if no scripts are
+    entered. This option can't be used if the `--startup` option is used.
+
+`-q`
+:   Sets the feedback mode to `concise`, which is the same as entering
+    `--feedback concise`.
+
+`-R`*flag*
+:   passes *flag* to the runtime system only when code snippets are executed.
+    For example, `-R-Dfoo=bar` means that execution of the snippet
+    `System.getProperty("foo")` will return `"bar"`.
+
+`-s`
+:   Sets the feedback mode to `silent`, which is the same as entering
+    `--feedback silent`.
+
+`--show-version`
+:   Prints version information and enters the tool.
+
+`--startup` *file*
+:   Overrides the default startup script for this session. The script can
+    contain any valid code snippets or commands.
+
+    The script can be a local file or one of the following predefined scripts:
+
+    `DEFAULT`
+    :   Loads the default entries, which are commonly used as imports.
+
+    `JAVASE`
+    :   Imports all Java SE packages.
+
+    `PRINTING`
+    :   Defines `print`, `println`, and `printf` as `jshell` methods for use
+        within the tool.
+
+    `TOOLING`
+    :   Defines `javac`, `jar`, and other methods for running JDK tools via
+        their command-line interface within the `jshell` tool.
+
+    For more than one script, provide a separate instance of this option for
+    each script. Startup scripts are run when JShell is first started and when
+    the session is restarted with the `/reset`, `/reload`, or `/env` command.
+    Startup scripts are run in the order in which they're entered on the
+    command line.
+
+    This option can't be used if the `--no-startup` option is used.
+
+`-v`
+:   Sets the feedback mode to `verbose`, which is the same as entering
+    `--feedback verbose`.
+
+`--version`
+:   Prints version information and exits the tool.
+
+## jshell Commands
+
+Within the `jshell` tool, commands are used to modify the environment and
+manage code snippets.
+
+`/drop` {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+:   Drops snippets identified by name, ID, or ID range, making them inactive.
+    For a range of IDs, provide the starting ID and ending ID separated with a
+    hyphen. To provide a list, separate the items in the list with a space. Use
+    the `/list` command to see the IDs of code snippets.
+
+`/edit` \[*option*\]
+:   Opens an editor. If no option is entered, then the editor opens with the
+    active snippets.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Opens the editor with the snippets identified by name, ID, or ID range.
+        For a range of IDs, provide the starting ID and ending ID separated
+        with a hyphen. To provide a list, separate the items in the list with a
+        space. Use the `/list` command to see the IDs of code snippets.
+
+    `-all`
+    :   Opens the editor with all snippets, including startup snippets and
+        snippets that failed, were overwritten, or were dropped.
+
+    `-start`
+    :   Opens the editor with startup snippets that were evaluated when JShell
+        was started.
+
+    To exit edit mode, close the editor window, or respond to the prompt
+    provided if the `-wait` option was used when the editor was set.
+
+    Use the `/set editor` command to specify the editor to use. If no editor is
+    set, then the following environment variables are checked in order:
+    `JSHELLEDITOR`, `VISUAL`, and `EDITOR`. If no editor is set in JShell and
+    none of the editor environment variables is set, then a simple default
+    editor is used.
+
+`/env` \[*options*\]
+:   Displays the environment settings, or updates the environment settings and
+    restarts the session. If no option is entered, then the current environment
+    settings are displayed. If one or more options are entered, then the
+    session is restarted as follows:
+
+    -   Updates the environment settings with the provided options.
+
+    -   Resets the execution state.
+
+    -   Runs the startup scripts.
+
+    -   Silently replays the history in the order entered. The history includes
+        all valid snippets or `/drop` commands entered at the `jshell` prompt,
+        in scripts entered on the command line, or scripts entered with the
+        `/open` command.
+
+    Environment settings entered on the command line or provided with a
+    previous `/reset`, `/env`, or `/reload` command are maintained unless an
+    *option* is entered that overwrites the setting.
+
+    The following options are valid:
+
+    `--add-modules` *module*\[`,`*module*...\]
+    :   Specifies the root modules to resolve in addition to the initial
+        module.
+
+    `--add-exports` *source-module*`/`*package*`=`*target-module*\[`,`*target-module*\]\*
+    :   Adds an export of *package* from *source-module* to *target-module*.
+
+    `--class-path` *path*
+    :   Specifies the directories and archives that are searched to locate
+        class files. This option overrides the path in the `CLASSPATH`
+        environment variable. If the environment variable isn't set and this
+        option isn't used, then the current directory is searched. For Linux
+        and macOS, use a colon (`:`) to separate items in the path. For Windows,
+        use a semicolon (`;`) to separate items.
+
+    `--module-path` *modulepath*
+    :   Specifies where to find application modules. For Linux and macOS, use
+        a colon (`:`) to separate items in the path. For Windows, use a
+        semicolon (`;`) to separate items.
+
+`/exit` \[*integer-expression-snippet*\]
+:   Exits the tool. If no snippet is entered, the exit status is zero. If a
+    snippet is entered and the result of the snippet is an integer, the result
+    is used as the exit status. If an error occurs, or the result of the
+    snippet is not an integer, an error is displayed and the tool remains
+    active.
+
+`/history`
+:   Displays what was entered in this session.
+
+`/help` \[*command*\|*subject*\]
+:   Displays information about commands and subjects. If no options are
+    entered, then a summary of information for all commands and a list of
+    available subjects are displayed. If a valid command is provided, then
+    expanded information for that command is displayed. If a valid subject is
+    entered, then information about that subject is displayed.
+
+    The following values for *subject* are valid:
+
+    `context`
+    :   Describes the options that are available for configuring the
+        environment.
+
+    `intro`
+    :   Provides an introduction to the tool.
+
+    `shortcuts`
+    :   Describes keystrokes for completing commands and snippets. See [Input
+        Shortcuts].
+
+`/imports`
+:   Displays the current active imports, including those from the startup
+    scripts and scripts that were entered on the command line when JShell was
+    started.
+
+`/list` \[*option*\]
+:   Displays a list of snippets and their IDs. If no option is entered, then
+    all active snippets are displayed, but startup snippets aren't.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Displays the snippets identified by name, ID, or ID range. For a range
+        of IDs, provide the starting ID and ending ID separated with a hyphen.
+        To provide a list, separate the items in the list with a space.
+
+    `-all`
+    :   Displays all snippets, including startup snippets and snippets that
+        failed, were overwritten, or were dropped. IDs that begin with `s` are
+        startup snippets. IDs that begin with `e` are snippets that failed.
+
+    `-start`
+    :   Displays startup snippets that were evaluated when JShell was started.
+
+`/methods` \[*option*\]
+:   Displays information about the methods that were entered. If no option is
+    entered, then the name, parameter types, and return type of all active
+    methods are displayed.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Displays information for methods identified by name, ID, or ID range.
+        For a range of IDs, provide the starting ID and ending ID separated
+        with a hyphen. To provide a list, separate the items in the list with a
+        space. Use the `/list` command to see the IDs of code snippets.
+
+    `-all`
+    :   Displays information for all methods, including those added when JShell
+        was started, and methods that failed, were overwritten, or were
+        dropped.
+
+    `-start`
+    :   Displays information for startup methods that were added when JShell
+        was started.
+
+`/open` *file*
+:   Opens the script specified and reads the snippets into the tool. The script
+    can be a local file or one of the following predefined scripts:
+
+    `DEFAULT`
+    :   Loads the default entries, which are commonly used as imports.
+
+    `JAVASE`
+    :   Imports all Java SE packages.
+
+    `PRINTING`
+    :   Defines `print`, `println`, and `printf` as `jshell` methods for use
+        within the tool.
+
+    `TOOLING`
+    :   Defines `javac`, `jar`, and other methods for running JDK tools via
+        their command-line interface within the `jshell` tool.
+
+`/reload` \[*options*\]
+:   Restarts the session as follows:
+
+    -   Updates the environment settings with the provided options, if any.
+
+    -   Resets the execution state.
+
+    -   Runs the startup scripts.
+
+    -   Replays the history in the order entered. The history includes all
+        valid snippets or `/drop` commands entered at the `jshell` prompt, in
+        scripts entered on the command line, or scripts entered with the
+        `/open` command.
+
+    Environment settings entered on the command line or provided with a
+    previous `/reset`, `/env`, or `/reload` command are maintained unless an
+    *option* is entered that overwrites the setting.
+
+    The following options are valid:
+
+    `--add-modules` *module*\[`,`*module*...\]
+    :   Specifies the root modules to resolve in addition to the initial
+        module.
+
+    `--add-exports` *source-module*`/`*package*`=`*target-module*\[`,`*target-module*\]\*
+    :   Adds an export of *package* from *source-module* to *target-module*.
+
+    `--class-path` *path*
+    :   Specifies the directories and archives that are searched to locate
+        class files. This option overrides the path in the `CLASSPATH`
+        environment variable. If the environment variable isn't set and this
+        option isn't used, then the current directory is searched. For Linux
+        and macOS, use a colon (`:`) to separate items in the path. For
+        Windows, use a semicolon (`;`) to separate items.
+
+    `--module-path` *modulepath*
+    :   Specifies where to find application modules. For Linux and macOS, use
+        a colon (`:`) to separate items in the path. For Windows, use a
+        semicolon (`;`) to separate items.
+
+    `-quiet`
+    :   Replays the valid history without displaying it. Errors are displayed.
+
+    `-restore`
+    :   Resets the environment to the state at the start of the previous run of
+        the tool or to the last time a `/reset`, `/reload`, or `/env` command
+        was executed in the previous run. The valid history since that point is
+        replayed. Use this option to restore a previous JShell session.
+
+`/reset` \[*options*\]
+:   Discards all entered snippets and restarts the session as follows:
+
+    -   Updates the environment settings with the provided options, if any.
+
+    -   Resets the execution state.
+
+    -   Runs the startup scripts.
+
+    History is not replayed. All code that was entered is lost.
+
+    Environment settings entered on the command line or provided with a
+    previous `/reset`, `/env`, or `/reload` command are maintained unless an
+    *option* is entered that overwrites the setting.
+
+    The following options are valid:
+
+    `--add-modules` *module*\[`,`*module*...\]
+    :   Specifies the root modules to resolve in addition to the initial
+        module.
+
+    `--add-exports` *source-module*`/`*package*`=`*target-module*\[`,`*target-module*\]\*
+    :   Adds an export of *package* from *source-module* to *target-module*.
+
+    `--class-path` *path*
+    :   Specifies the directories and archives that are searched to locate
+        class files. This option overrides the path in the `CLASSPATH`
+        environment variable. If the environment variable isn't set and this
+        option isn't used, then the current directory is searched. For Linux
+        and macOS, use a colon (`:`) to separate items in the path. For
+        Windows, use a semicolon (`;`) to separate items.
+
+    `--module-path` *modulepath*
+    :   Specifies where to find application modules. For Linux and macOS, use
+        a colon (`:`) to separate items in the path. For Windows, use a
+        semicolon (`;`) to separate items.
+
+`/save` \[*options*\] *file*
+:   Saves snippets and commands to the file specified. If no options are
+    entered, then active snippets are saved.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Saves the snippets and commands identified by name, ID, or ID range.
+        For a range of IDs, provide the starting ID and ending ID separated
+        with a hyphen. To provide a list, separate the items in the list with a
+        space. Use the `/list` command to see the IDs of the code snippets.
+
+    `-all`
+    :   Saves all snippets, including startup snippets and snippets that were
+        overwritten or failed.
+
+    `-history`
+    :   Saves the sequential history of all commands and snippets entered in
+        the current session.
+
+    `-start`
+    :   Saves the current startup settings. If no startup scripts were
+        provided, then an empty file is saved.
+
+`/set` \[*setting*\]
+:   Sets configuration information, including the external editor, startup
+    settings, and feedback mode. This command is also used to create a custom
+    feedback mode with customized prompt, format, and truncation values. If no
+    setting is entered, then the current setting for the editor, startup
+    settings, and feedback mode are displayed.
+
+    The following values are valid for `setting`:
+
+    `editor` \[*options*\] \[*command*\]
+    :   Sets the command used to start an external editor when the `/edit`
+        command is entered. The command can include command arguments separated
+        by spaces. If no command or options are entered, then the current
+        setting is displayed.
+
+        The following options are valid:
+
+        `-default`
+        :   Sets the editor to the default editor provided with JShell. This
+            option can't be used if a command for starting an editor is
+            entered.
+
+        `-delete`
+        :   Sets the editor to the one in effect when the session started. If
+            used with the `-retain` option, then the retained editor setting is
+            deleted and the editor is set to the first of the following
+            environment variables found: `JSHELLEDITOR`, `VISUAL`, or `EDITOR`.
+            If none of the editor environment variables are set, then this
+            option sets the editor to the default editor.
+
+            This option can't be used if a command for starting an editor is
+            entered.
+
+        `-retain`
+        :   Saves the editor setting across sessions. If no other option or a
+            command is entered, then the current setting is saved.
+
+        `-wait`
+        :   Prompts the user to indicate when editing is complete. Otherwise
+            control returns to JShell when the editor exits. Use this option if
+            the editor being used exits immediately, for example, when an edit
+            window already exists. This option is valid only when a command for
+            starting an editor is entered.
+
+    `feedback` \[*mode*\]
+    :   Sets the feedback mode used to respond to input. If no mode is entered,
+        then the current mode is displayed.
+
+        The following modes are valid: `concise`, `normal`, `silent`,
+        `verbose`, and any custom mode created with the `/set mode` command.
+
+    `format` *mode* *field* `"`*format-string*`"` *selector*
+    :   Sets the format of the feedback provided in response to input. If no
+        mode is entered, then the current formats for all fields for all
+        feedback modes are displayed. If only a mode is entered, then the
+        current formats for that mode are displayed. If only a mode and field
+        are entered, then the current formats for that field are displayed.
+
+        To define a format, the following arguments are required:
+
+        *mode*
+        :   Specifies a feedback mode to which the response format is applied.
+            Only custom modes created with the `/set mode` command can be
+            modified.
+
+        *field*
+        :   Specifies a context-specific field to which the response format is
+            applied. The fields are described in the online help, which is
+            accessed from JShell using the `/help /set format` command.
+
+        `"`*format-string*`"`
+        :   Specifies the string to use as the response format for the
+            specified field and selector. The structure of the format string is
+            described in the online help, which is accessed from JShell using
+            the `/help /set format` command.
+
+        *selector*
+        :   Specifies the context in which the response format is applied. The
+            selectors are described in the online help, which is accessed from
+            JShell using the `/help /set format` command.
+
+    `mode` \[*mode-name*\] \[*existing-mode*\] \[*options*\]
+    :   Creates a custom feedback mode with the mode name provided. If no mode
+        name is entered, then the settings for all modes are displayed, which
+        includes the mode, prompt, format, and truncation settings. If the name
+        of an existing mode is provided, then the settings from the existing
+        mode are copied to the mode being created.
+
+        The following options are valid:
+
+        `-command`\|`-quiet`
+        :   Specifies the level of feedback displayed for commands when using
+            the mode. This option is required when creating a feedback mode.
+            Use `-command` to show information and verification feedback for
+            commands. Use `-quiet` to show only essential feedback for
+            commands, such as error messages.
+
+        `-delete`
+        :   Deletes the named feedback mode for this session. The name of the
+            mode to delete is required. To permanently delete a retained mode,
+            use the `-retain` option with this option. Predefined modes can't
+            be deleted.
+
+        `-retain`
+        :   Saves the named feedback mode across sessions. The name of the mode
+            to retain is required.
+
+        Configure the new feedback mode using the `/set prompt`, `/set format`,
+        and `/set truncation` commands.
+
+        To start using the new mode, use the `/set feedback` command.
+
+    `prompt` *mode* `"`*prompt-string*`"` `"`*continuation-prompt-string*`"`
+    :   Sets the prompts for input within JShell. If no mode is entered, then
+        the current prompts for all feedback modes are displayed. If only a
+        mode is entered, then the current prompts for that mode are displayed.
+
+        To define a prompt, the following arguments are required:
+
+        *mode*
+        :   Specifies the feedback mode to which the prompts are applied. Only
+            custom modes created with the `/set mode` command can be modified.
+
+        `"`*prompt-string*`"`
+        :   Specifies the string to use as the prompt for the first line of
+            input.
+
+        `"`*continuation-prompt-string*`"`
+        :   Specifies the string to use as the prompt for the additional input
+            lines needed to complete a snippet.
+
+    `start` \[`-retain`\] \[*file* \[*file*...\]\|*option*\]
+    :   Sets the names of the startup scripts used when the next `/reset`,
+        `/reload`, or `/env` command is entered. If more than one script is
+        entered, then the scripts are run in the order entered. If no scripts
+        or options are entered, then the current startup settings are
+        displayed.
+
+        The scripts can be local files or one of the following predefined
+        scripts:
+
+        `DEFAULT`
+        :   Loads the default entries, which are commonly used as imports.
+
+        `JAVASE`
+        :   Imports all Java SE packages.
+
+        `PRINTING`
+        :   Defines `print`, `println`, and `printf` as `jshell` methods for
+            use within the tool.
+
+        `TOOLING`
+        :   Defines `javac`, `jar`, and other methods for running JDK tools via
+            their command-line interface within the `jshell` tool.
+
+        The following options are valid:
+
+        `-default`
+        :   Sets the startup settings to the default settings.
+
+        `-none`
+        :   Specifies that no startup settings are used.
+
+        Use the `-retain` option to save the start setting across sessions.
+
+    `truncation` *mode* *length* *selector*
+    :   Sets the maximum length of a displayed value. If no mode is entered,
+        then the current truncation values for all feedback modes are
+        displayed. If only a mode is entered, then the current truncation
+        values for that mode are displayed.
+
+        To define truncation values, the following arguments are required:
+
+        *mode*
+        :   Specifies the feedback mode to which the truncation value is
+            applied. Only custom modes created with the `/set mode` command can
+            be modified.
+
+        *length*
+        :   Specifies the unsigned integer to use as the maximum length for the
+            specified selector.
+
+        *selector*
+        :   Specifies the context in which the truncation value is applied. The
+            selectors are described in the online help, which is accessed from
+            JShell using the `/help /set truncation` command.
+
+`/types` \[*option*\]
+:   Displays classes, interfaces, and enums that were entered. If no option is
+    entered, then all current active classes, interfaces, and enums are
+    displayed.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Displays information for classes, interfaces, and enums identified by
+        name, ID, or ID range. For a range of IDs, provide the starting ID and
+        ending ID separated with a hyphen. To provide a list, separate the
+        items in the list with a space. Use the `/list` command to see the IDs
+        of the code snippets.
+
+    `-all`
+    :   Displays information for all classes, interfaces, and enums, including
+        those added when JShell was started, and classes, interfaces, and enums
+        that failed, were overwritten, or were dropped.
+
+    `-start`
+    :   Displays information for startup classes, interfaces, and enums that
+        were added when JShell was started.
+
+`/vars` \[*option*\]
+:   Displays the name, type, and value of variables that were entered. If no
+    option is entered, then all current active variables are displayed.
+
+    The following options are valid:
+
+    {*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+    :   Displays information for variables identified by name, ID, or ID range.
+        For a range of IDs, provide the starting ID and ending ID separated
+        with a hyphen. To provide a list, separate the items in the list with a
+        space. Use the `/list` command to see the IDs of the code snippets.
+
+    `-all`
+    :   Displays information for all variables, including those added when
+        JShell was started, and variables that failed, were overwritten, or
+        were dropped.
+
+    `-start`
+    :   Displays information for startup variables that were added when JShell
+        was started.
+
+`/?`
+:   Same as the `/help` command.
+
+`/!`
+:   Reruns the last snippet.
+
+`/`{*name*\|*id*\|*startID*`-`*endID*} \[{*name*\|*id*\|*startID*`-`*endID*}...\]
+:   Reruns the snippets identified by ID, range of IDs, or name. For a range of
+    IDs, provide the starting ID and ending ID separated with a hyphen. To
+    provide a list, separate the items in the list with a space. The first item
+    in the list must be an ID or ID range. Use the `/list` command to see the
+    IDs of the code snippets.
+
+`/-`*n*
+:   Reruns the -*n*th previous snippet. For example, if 15 code snippets were
+    entered, then `/-4` runs the 11th snippet. Commands aren't included in the
+    count.
+
+## Input Shortcuts
+
+The following shortcuts are available for entering commands and snippets in
+JShell.
+
+### Tab completion
+
+**\<tab\>**
+:   When entering snippets, commands, subcommands, command arguments, or
+    command options, use the Tab key to automatically complete the item. If the
+    item can't be determined from what was entered, then possible options are
+    provided.
+
+    When entering a method call, use the Tab key after the method call's
+    opening parenthesis to see the parameters for the method. If the method has
+    more than one signature, then all signatures are displayed. Pressing the
+    Tab key a second time displays the description of the method and the
+    parameters for the first signature. Continue pressing the Tab key for a
+    description of any additional signatures.
+
+**Shift+\<Tab\> V**
+:   After entering a complete expression, use this key sequence to convert the
+    expression to a variable declaration of a type determined by the type of
+    the expression.
+
+**Shift+\<Tab\> M**
+:   After entering a complete expression or statement, use this key sequence to
+    convert the expression or statement to a method declaration. If an
+    expression is entered, the return type is based on the type of the
+    expression.
+
+**Shift+\<Tab\> I**
+:   When an identifier is entered that can't be resolved, use this key sequence
+    to show possible imports that resolve the identifier based on the content
+    of the specified class path.
+
+### Command abbreviations
+
+An abbreviation of a command is accepted if the abbreviation uniquely
+identifies a command. For example, `/l` is recognized as the `/list` command.
+However, `/s` isn't a valid abbreviation because it can't be determined if the
+`/set` or `/save` command is meant. Use `/se` for the `/set` command or `/sa`
+for the `/save` command.
+
+Abbreviations are also accepted for subcommands, command arguments, and command
+options. For example, use `/m -a` to display all methods.
+
+### History navigation
+
+A history of what was entered is maintained across sessions. Use the up and
+down arrows to scroll through commands and snippets from the current and past
+sessions. Use the Ctrl key with the up and down arrows to skip all but the
+first line of multiline snippets.
+
+### History search
+
+Use the Ctrl+R key combination to search the history for the string entered.
+The prompt changes to show the string and the match. Ctrl+R searches backwards
+from the current location in the history through earlier entries. Ctrl+S
+searches forward from the current location in the history though later entries.
+
+## Input Editing
+
+The editing capabilities of JShell are similar to that of other common shells.
+Keyboard keys and key combinations provide line editing shortcuts. The Ctrl key
+and Meta key are used in key combinations. If your keyboard doesn't have a Meta
+key, then the Alt key is often mapped to provide Meta key functionality.
+
+Table: Line Editing Shortcuts
+
+Key or Key Combination   Action
+-----------------------  -------
+Return                   Enter the current line.
+Left arrow               Move the cursor to the left one character.
+Right arrow              Move the cursor to the right one character.
+Ctrl+A                   Move the cursor to the beginning of the line.
+Ctrl+E                   Move the cursor to the end of the line.
+Meta+B                   Move the cursor to the left one word.
+Meta+F                   Move the cursor to the right one word.
+Delete                   Delete the character under the cursor.
+Backspace                Delete the character before the cursor.
+Ctrl+K                   Delete the text from the cursor to the end of the line.
+Meta+D                   Delete the text from the cursor to the end of the word.
+Ctrl+W                   Delete the text from the cursor to the previous white space.
+Ctrl+Y                   Paste the most recently deleted text into the line.
+Meta+Y                   After Ctrl+Y, press to cycle through the previously deleted text.
+-----------------------  -------
+
+## Example of Starting and Stopping a JShell Session
+
+JShell is provided with the JDK. To start a session, enter `jshell` on the
+command line. A welcome message is printed, and a prompt for entering commands
+and snippets is provided.
+
+```
+% jshell
+|  Welcome to JShell -- Version 9
+|  For an introduction type: /help intro
+
+jshell>
+```
+
+To see which snippets were automatically loaded when JShell started, use the
+`/list -start` command. The default startup snippets are import statements for
+common packages. The ID for each snippet begins with the letter *s*, which
+indicates it's a startup snippet.
+
+```
+jshell> /list -start
+
+  s1 : import java.io.*;
+  s2 : import java.math.*;
+  s3 : import java.net.*;
+  s4 : import java.nio.file.*;
+  s5 : import java.util.*;
+  s6 : import java.util.concurrent.*;
+  s7 : import java.util.function.*;
+  s8 : import java.util.prefs.*;
+  s9 : import java.util.regex.*;
+ s10 : import java.util.stream.*;
+
+jshell>
+```
+
+To end the session, use the `/exit` command.
+
+```
+jshell> /exit
+|  Goodbye
+
+%
+```
+
+## Example of Entering Snippets
+
+Snippets are Java statements, variable definitions, method definitions, class
+definitions, import statements, and expressions. Terminating semicolons are
+automatically added to the end of a completed snippet if they're missing.
+
+The following example shows two variables and a method being defined, and the
+method being run. Note that a scratch variable is automatically created to hold
+the result because no variable was provided.
+
+```
+jshell> int a=4
+a ==> 4
+
+jshell> int b=8
+b ==> 8
+
+jshell> int square(int i1) {
+   ...> return i1 * i1;
+   ...> }
+|  created method square(int)
+
+jshell> square(b)
+$5 ==> 64
+```
+
+## Example of Changing Snippets
+
+Change the definition of a variable, method, or class by entering it again.
+
+The following examples shows a method being defined and the method run:
+
+```
+jshell> String grade(int testScore) {
+   ...>     if (testScore >= 90) {
+   ...>         return "Pass";
+   ...>     }
+   ...>     return "Fail";
+   ...> }
+|  created method grade(int)
+
+jshell> grade(88)
+$3 ==> "Fail"
+```
+
+To change the method `grade` to allow more students to pass, enter the method
+definition again and change the pass score to `80`. Use the up arrow key to
+retrieve the previous entries to avoid having to reenter them and make the
+change in the `if` statement. The following example shows the new definition
+and reruns the method to show the new result:
+
+```
+jshell> String grade(int testScore) {
+   ...>     if (testScore >= 80) {
+   ...>         return "Pass";
+   ...>     }
+   ...>     return "Fail";
+   ...> }
+|  modified method grade(int)
+
+jshell> grade(88)
+$5 ==> "Pass"
+```
+
+For snippets that are more than a few lines long, or to make more than a few
+changes, use the `/edit` command to open the snippet in an editor. After the
+changes are complete, close the edit window to return control to the JShell
+session. The following example shows the command and the feedback provided when
+the edit window is closed. The `/list` command is used to show that the pass
+score was changed to `85`.
+
+```
+jshell> /edit grade
+|  modified method grade(int)
+jshell> /list grade
+
+   6 : String grade(int testScore) {
+           if (testScore >= 85) {
+               return "Pass";
+           }
+           return "Fail";
+       }
+```
+
+## Example of Creating a Custom Feedback Mode
+
+The feedback mode determines the prompt that's displayed, the feedback messages
+that are provided as snippets are entered, and the maximum length of a
+displayed value. Predefined feedback modes are provided. Commands for creating
+custom feedback modes are also provided.
+
+Use the `/set mode` command to create a new feedback mode. In the following
+example, the new mode `mymode`, is based on the predefined feedback mode,
+`normal`, and verifying command feedback is displayed:
+
+```
+jshell> /set mode mymode normal -command
+|  Created new feedback mode: mymode
+```
+
+Because the new mode is based on the `normal` mode, the prompts are the same.
+The following example shows how to see what prompts are used and then changes
+the prompts to custom strings. The first string represents the standard JShell
+prompt. The second string represents the prompt for additional lines in
+multiline snippets.
+
+```
+jshell> /set prompt mymode
+|  /set prompt mymode "\njshell> " "   ...> "
+
+jshell> /set prompt mymode "\nprompt$ " "   continue$ "
+```
+
+The maximum length of a displayed value is controlled by the truncation
+setting. Different types of values can have different lengths. The following
+example sets an overall truncation value of 72, and a truncation value of 500
+for variable value expressions:
+
+```
+jshell> /set truncation mymode 72
+
+jshell> /set truncation mymode 500 varvalue
+```
+
+The feedback displayed after snippets are entered is controlled by the format
+setting and is based on the type of snippet entered and the action taken for
+that snippet. In the predefined mode `normal`, the string `created` is
+displayed when a method is created. The following example shows how to change
+that string to `defined`:
+
+```
+jshell> /set format mymode action "defined" added-primary
+```
+
+Use the `/set feedback` command to start using the feedback mode that was just
+created. The following example shows the custom mode in use:
+
+```
+jshell> /set feedback mymode
+|  Feedback mode: mymode
+
+prompt$ int square (int num1){
+   continue$ return num1*num1;
+   continue$ }
+|  defined method square(int)
+
+prompt$
+```
diff --git a/src/jdk.jstatd/share/man/jstatd.1 b/src/jdk.jstatd/share/man/jstatd.1
deleted file mode 100644
index f5d2f347b45..00000000000
--- a/src/jdk.jstatd/share/man/jstatd.1
+++ /dev/null
@@ -1,219 +0,0 @@
-.\" Copyright (c) 2004, 2024, 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.
-.\"
-.\" This code is distributed in the hope that it will be useful, but WITHOUT
-.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-.\" version 2 for more details (a copy is included in the LICENSE file that
-.\" accompanied this code).
-.\"
-.\" You should have received a copy of the GNU General Public License version
-.\" 2 along with this work; if not, write to the Free Software Foundation,
-.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" 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.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[R]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "JSTATD" "1" "2025" "JDK 24-ea" "JDK Commands"
-.hy
-.SH NAME
-.PP
-jstatd - monitor the creation and termination of instrumented Java
-HotSpot VMs
-.SH SYNOPSIS
-.PP
-\f[B]WARNING:\f[R] This command is experimental, unsupported, and
-deprecated.
-It will be removed in a future release.
-.PP
-\f[V]jstatd\f[R] [\f[I]options\f[R]]
-.TP
-\f[I]options\f[R]
-This represents the \f[V]jstatd\f[R] command-line options.
-See \f[B]Options for the jstatd Command\f[R].
-.SH DESCRIPTION
-.PP
-The \f[V]jstatd\f[R] command is an RMI server application that monitors
-for the creation and termination of instrumented Java HotSpot VMs and
-provides an interface to enable remote monitoring tools, \f[V]jstat\f[R]
-and \f[V]jps\f[R], to attach to JVMs that are running on the local host
-and collect information about the JVM process.
-.PP
-The \f[V]jstatd\f[R] server requires an RMI registry on the local host.
-The \f[V]jstatd\f[R] server attempts to attach to the RMI registry on
-the default port, or on the port you specify with the \f[V]-p\f[R]
-\f[V]port\f[R] option.
-If an RMI registry is not found, then one is created within the
-\f[V]jstatd\f[R] application that\[aq]s bound to the port that\[aq]s
-indicated by the \f[V]-p\f[R] \f[V]port\f[R] option or to the default
-RMI registry port when the \f[V]-p\f[R] \f[V]port\f[R] option is
-omitted.
-You can stop the creation of an internal RMI registry by specifying the
-\f[V]-nr\f[R] option.
-.SH OPTIONS FOR THE JSTATD COMMAND
-.TP
-\f[V]-nr\f[R]
-This option does not attempt to create an internal RMI registry within
-the \f[V]jstatd\f[R] process when an existing RMI registry isn\[aq]t
-found.
-.TP
-\f[V]-p\f[R] \f[I]port\f[R]
-This option sets the port number where the RMI registry is expected to
-be found, or when not found, created if the \f[V]-nr\f[R] option
-isn\[aq]t specified.
-.TP
-\f[V]-r\f[R] \f[I]rmiport\f[R]
-This option sets the port number to which the RMI connector is bound.
-If not specified a random available port is used.
-.TP
-\f[V]-n\f[R] \f[I]rminame\f[R]
-This option sets the name to which the remote RMI object is bound in the
-RMI registry.
-The default name is \f[V]JStatRemoteHost\f[R].
-If multiple \f[V]jstatd\f[R] servers are started on the same host, then
-the name of the exported RMI object for each server can be made unique
-by specifying this option.
-However, doing so requires that the unique server name be included in
-the monitoring client\[aq]s \f[V]hostid\f[R] and \f[V]vmid\f[R] strings.
-.TP
-\f[V]-J\f[R]\f[I]option\f[R]
-This option passes a Java \f[V]option\f[R] to the JVM, where the option
-is one of those described on the reference page for the Java application
-launcher.
-For example, \f[V]-J-Xms48m\f[R] sets the startup memory to 48 MB.
-See \f[B]java\f[R].
-.SH SECURITY
-.PP
-The \f[V]jstatd\f[R] server can monitor only JVMs for which it has the
-appropriate native access permissions.
-Therefore, the \f[V]jstatd\f[R] process must be running with the same
-user credentials as the target JVMs.
-Some user credentials, such as the root user in Linux and macOS
-operating systems, have permission to access the instrumentation
-exported by any JVM on the system.
-A \f[V]jstatd\f[R] process running with such credentials can monitor any
-JVM on the system, but introduces additional security concerns.
-.PP
-The \f[V]jstatd\f[R] server doesn\[aq]t provide any authentication of
-remote clients.
-Therefore, running a \f[V]jstatd\f[R] server process exposes the
-instrumentation export by all JVMs for which the \f[V]jstatd\f[R]
-process has access permissions to any user on the network.
-This exposure might be undesirable in your environment, and therefore,
-local security policies should be considered before you start the
-\f[V]jstatd\f[R] process, particularly in production environments or on
-networks that aren\[aq]t secure.
-.PP
-For security purposes, the \f[V]jstatd\f[R] server uses an RMI
-ObjectInputFilter to allow only essential classes to be deserialized.
-.PP
-If your security concerns can\[aq]t be addressed, then the safest action
-is to not run the \f[V]jstatd\f[R] server and use the \f[V]jstat\f[R]
-and \f[V]jps\f[R] tools locally.
-However, when using \f[V]jps\f[R] to get a list of instrumented JVMs,
-the list will not include any JVMs running in docker containers.
-.SH REMOTE INTERFACE
-.PP
-The interface exported by the \f[V]jstatd\f[R] process is proprietary
-and guaranteed to change.
-Users and developers are discouraged from writing to this interface.
-.SH EXAMPLES
-.PP
-The following are examples of the \f[V]jstatd\f[R] command.
-The \f[V]jstatd\f[R] scripts automatically start the server in the
-background.
-.SH INTERNAL RMI REGISTRY
-.PP
-This example shows how to start a \f[V]jstatd\f[R] session with an
-internal RMI registry.
-This example assumes that no other server is bound to the default RMI
-registry port (port \f[V]1099\f[R]).
-.RS
-.PP
-\f[V]jstatd\f[R]
-.RE
-.SH EXTERNAL RMI REGISTRY
-.PP
-This example starts a \f[V]jstatd\f[R] session with an external RMI
-registry.
-.IP
-.nf
-\f[CB]
-rmiregistry&
-jstatd
-\f[R]
-.fi
-.PP
-This example starts a \f[V]jstatd\f[R] session with an external RMI
-registry server on port \f[V]2020\f[R].
-.IP
-.nf
-\f[CB]
-jrmiregistry 2020&
-jstatd -p 2020
-\f[R]
-.fi
-.PP
-This example starts a \f[V]jstatd\f[R] session with an external RMI
-registry server on port \f[V]2020\f[R] and JMX connector bound to port
-\f[V]2021\f[R].
-.IP
-.nf
-\f[CB]
-jrmiregistry 2020&
-jstatd -p 2020 -r 2021
-\f[R]
-.fi
-.PP
-This example starts a \f[V]jstatd\f[R] session with an external RMI
-registry on port 2020 that\[aq]s bound to
-\f[V]AlternateJstatdServerName\f[R].
-.IP
-.nf
-\f[CB]
-rmiregistry 2020&
-jstatd -p 2020 -n AlternateJstatdServerName
-\f[R]
-.fi
-.SH STOP THE CREATION OF AN IN-PROCESS RMI REGISTRY
-.PP
-This example starts a \f[V]jstatd\f[R] session that doesn\[aq]t create
-an RMI registry when one isn\[aq]t found.
-This example assumes an RMI registry is already running.
-If an RMI registry isn\[aq]t running, then an error message is
-displayed.
-.RS
-.PP
-\f[V]jstatd -nr\f[R]
-.RE
-.SH ENABLE RMI LOGGING
-.PP
-This example starts a \f[V]jstatd\f[R] session with RMI logging
-capabilities enabled.
-This technique is useful as a troubleshooting aid or for monitoring
-server activities.
-.RS
-.PP
-\f[V]jstatd -J-Djava.rmi.server.logCalls=true\f[R]
-.RE
diff --git a/src/jdk.jstatd/share/man/jstatd.md b/src/jdk.jstatd/share/man/jstatd.md
new file mode 100644
index 00000000000..d068fddeb01
--- /dev/null
+++ b/src/jdk.jstatd/share/man/jstatd.md
@@ -0,0 +1,180 @@
+---
+# Copyright (c) 2004, 2024, 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.
+#
+# This code is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# version 2 for more details (a copy is included in the LICENSE file that
+# accompanied this code).
+#
+# You should have received a copy of the GNU General Public License version
+# 2 along with this work; if not, write to the Free Software Foundation,
+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# 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.
+#
+
+title: 'JSTATD(1) JDK @@VERSION_SHORT@@ | JDK Commands'
+date: @@COPYRIGHT_YEAR@@
+lang: en
+---
+
+## Name
+
+jstatd - monitor the creation and termination of instrumented Java HotSpot VMs
+
+## Synopsis
+
+**WARNING:** This command is experimental, unsupported, and deprecated. It will be removed in a future release.
+
+`jstatd` \[*options*\]
+
+*options*
+:   This represents the `jstatd` command-line options. See [Options for the
+    jstatd Command].
+
+## Description
+
+The `jstatd` command is an RMI server application that monitors for the
+creation and termination of instrumented Java HotSpot VMs and provides an
+interface to enable remote monitoring tools, `jstat` and `jps`, to attach to
+JVMs that are running on the local host and collect information about the JVM
+process.
+
+The `jstatd` server requires an RMI registry on the local host. The `jstatd`
+server attempts to attach to the RMI registry on the default port, or on the
+port you specify with the `-p` `port` option. If an RMI registry is not found,
+then one is created within the `jstatd` application that's bound to the port
+that's indicated by the `-p` `port` option or to the default RMI registry port
+when the `-p` `port` option is omitted. You can stop the creation of an
+internal RMI registry by specifying the `-nr` option.
+
+## Options for the jstatd Command
+
+`-nr`
+:   This option does not attempt to create an internal RMI registry within the
+    `jstatd` process when an existing RMI registry isn't found.
+
+`-p` *port*
+:   This option sets the port number where the RMI registry is expected to be
+    found, or when not found, created if the `-nr` option isn't specified.
+
+`-r` *rmiport*
+:   This option sets the port number to which the RMI connector is bound. If
+    not specified a random available port is used.
+
+`-n` *rminame*
+:   This option sets the name to which the remote RMI object is bound in the
+    RMI registry. The default name is `JStatRemoteHost`. If multiple `jstatd`
+    servers are started on the same host, then the name of the exported RMI
+    object for each server can be made unique by specifying this option.
+    However, doing so requires that the unique server name be included in the
+    monitoring client's `hostid` and `vmid` strings.
+
+`-J`*option*
+:   This option passes a Java `option` to the JVM, where the option is one of
+    those described on the reference page for the Java application launcher.
+    For example, `-J-Xms48m` sets the startup memory to 48 MB. See
+    [java](java.html).
+
+## Security
+
+The `jstatd` server can monitor only JVMs for which it has the appropriate
+native access permissions. Therefore, the `jstatd` process must be running with
+the same user credentials as the target JVMs. Some user credentials, such as
+the root user in Linux and macOS operating systems, have
+permission to access the instrumentation exported by any JVM on the system. A
+`jstatd` process running with such credentials can monitor any JVM on the
+system, but introduces additional security concerns.
+
+The `jstatd` server doesn't provide any authentication of remote clients.
+Therefore, running a `jstatd` server process exposes the instrumentation export
+by all JVMs for which the `jstatd` process has access permissions to any user
+on the network. This exposure might be undesirable in your environment, and
+therefore, local security policies should be considered before you start the
+`jstatd` process, particularly in production environments or on networks that
+aren't secure.
+
+For security purposes, the `jstatd` server uses an RMI ObjectInputFilter to allow
+only essential classes to be deserialized.
+
+If your security concerns can't be addressed,
+then the safest action is to not run the `jstatd` server and use the `jstat`
+and `jps` tools locally. However, when using `jps` to get a list of
+instrumented JVMs, the list will not include any JVMs running in docker
+containers.
+
+## Remote Interface
+
+The interface exported by the `jstatd` process is proprietary and guaranteed to
+change. Users and developers are discouraged from writing to this interface.
+
+## Examples
+
+The following are examples of the `jstatd` command. The `jstatd` scripts
+automatically start the server in the background.
+
+## Internal RMI Registry
+
+This example shows how to start a `jstatd` session with an internal RMI
+registry. This example assumes that no other server is bound to the default RMI
+registry port (port `1099`).
+
+>   `jstatd`
+
+## External RMI Registry
+
+This example starts a `jstatd` session with an external RMI registry.
+
+```
+rmiregistry&
+jstatd
+```
+
+This example starts a `jstatd` session with an external RMI registry server on
+port `2020`.
+
+```
+jrmiregistry 2020&
+jstatd -p 2020
+```
+
+This example starts a `jstatd` session with an external RMI registry server on
+port `2020` and JMX connector bound to port `2021`.
+
+```
+jrmiregistry 2020&
+jstatd -p 2020 -r 2021
+```
+
+This example starts a `jstatd` session with an external RMI registry on port
+2020 that's bound to `AlternateJstatdServerName`.
+
+```
+rmiregistry 2020&
+jstatd -p 2020 -n AlternateJstatdServerName
+```
+
+## Stop the Creation of an In-Process RMI Registry
+
+This example starts a `jstatd` session that doesn't create an RMI registry when
+one isn't found. This example assumes an RMI registry is already running. If an
+RMI registry isn't running, then an error message is displayed.
+
+>   `jstatd -nr`
+
+## Enable RMI Logging
+
+This example starts a `jstatd` session with RMI logging capabilities enabled.
+This technique is useful as a troubleshooting aid or for monitoring server
+activities.
+
+>   `jstatd
+    -J-Djava.rmi.server.logCalls=true`
diff --git a/test/langtools/jdk/javadoc/tool/CheckManPageOptions.java b/test/langtools/jdk/javadoc/tool/CheckManPageOptions.java
index 2e2d0d0f84d..41bff3906d4 100644
--- a/test/langtools/jdk/javadoc/tool/CheckManPageOptions.java
+++ b/test/langtools/jdk/javadoc/tool/CheckManPageOptions.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2021, 2024, 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
@@ -138,7 +138,7 @@ public class CheckManPageOptions {
     }
 
     Path findDefaultFile() {
-        return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.1");
+        return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.md");
     }
 
     Path findRootDir() {
@@ -264,29 +264,32 @@ public class CheckManPageOptions {
         var list = new ArrayList<String>();
         // In the Markdown man page, options are defined in one of two forms:
         // 1. options delegated to javac appear in lines of the form
-        //      -   `-...
+        //      * <span id="...">`-...</span>
         // 2. options implemented by the tool or doclet appear in lines of the form
-        //      `-...`
+        //      <span id="...">`-...</span>
 
-        Pattern p1 = Pattern.compile("\\R-   `-.*");
-        Pattern p2 = Pattern.compile("\\R`-.*");
+        Pattern p1 = Pattern.compile("\\R* <span id=\"[^\"]+\">`-.*</span>");
+        Pattern p2 = Pattern.compile("\\R<span id=\"[^\"]+\">`-.*</span>");
         Pattern outer = Pattern.compile("(" + p1.pattern() + "|" + p2.pattern() + ")");
         Matcher outerMatcher = outer.matcher(page);
 
         // In the defining areas, option names are represented as follows:
-        //      `OPTION`
-        // where OPTION is the shortest string not containing whitespace or colon
-        Pattern inner = Pattern.compile("\\s`([^:`]+)");
+        //      `OPTION` or `OPTION`
+        // where OPTION is the shortest string not containing whitespace or colon,
+        // and in which all '-' characters are escaped with a single backslash.
+        Pattern inner = Pattern.compile("[>\\s]`(-[^ :]+?)(:|`)");
 
         while (outerMatcher.find()) {
             String lines = outerMatcher.group();
-            out.println("found:" + lines + "\n");
+            out.println("found:" + lines);
 
             Matcher innerMatcher = inner.matcher(lines);
             while (innerMatcher.find()) {
                 String option = innerMatcher.group(1);
+                out.println("  found option:" + option);
                 list.add(option);
             }
+            out.println();
         }
 
         return list;