1JAVA(1) JDK Commands JAVA(1)
2
6 java - launch a Java application
7
9 To launch a class file:
10 java [options] mainclass [args ...]
12 To launch the main class in a JAR file:
14 java [options] -jar jarfile [args ...]
16 To launch the main class in a module:
18 java [options] -m module[/mainclass] [args ...]
20 or
22 java [options] --module module[/mainclass] [args ...]
24 To launch a single source-file program:
26 java [options] source-file [args ...]
28 options
30 Optional: Specifies command-line options separated by spaces.
31 See Overview of Java Options for a description of available op‐
32 tions.
33 mainclass
35 Specifies the name of the class to be launched. Command-line
36 entries following classname are the arguments for the main meth‐
37 od.
38 -jar jarfile
40 Executes a program encapsulated in a JAR file. The jarfile ar‐
41 gument is the name of a JAR file with a manifest that contains a
42 line in the form Main-Class:classname that defines the class
43 with the public static void main(String[] args) method that
44 serves as your application's starting point. When you use -jar,
45 the specified JAR file is the source of all user classes, and
46 other class path settings are ignored. If you're using JAR
47 files, then see jar.
48 -m or --module module[/mainclass]
50 Executes the main class in a module specified by mainclass if it
51 is given, or, if it is not given, the value in the module. In
52 other words, mainclass can be used when it is not specified by
53 the module, or to override the value when it is specified.
54 See Standard Options for Java.
56 source-file
58 Only used to launch a single source-file program. Specifies the
59 source file that contains the main class when using source-file
60 mode. See Using Source-File Mode to Launch Single-File
61 Source-Code Programs
62 args ...
64 Optional: Arguments following mainclass, source-file, -jar
65 jarfile, and -m or --module module/mainclass are passed as argu‐
66 ments to the main class.
67
69 The java command starts a Java application. It does this by starting
70 the Java Virtual Machine (JVM), loading the specified class, and call‐
71 ing that class's main() method. The method must be declared public and
72 static, it must not return any value, and it must accept a String array
73 as a parameter. The method declaration has the following form:
74 public static void main(String[] args)
76 In source-file mode, the java command can launch a class declared in a
78 source file. See Using Source-File Mode to Launch Single-File
79 Source-Code Programs for a description of using the source-file mode.
80 Note: You can use the JDK_JAVA_OPTIONS launcher environment
82 variable to prepend its content to the actual command line of
83 the java launcher. See Using the JDK_JAVA_OPTIONS Launcher En‐
84 vironment Variable.
85 By default, the first argument that isn't an option of the java command
87 is the fully qualified name of the class to be called. If -jar is
88 specified, then its argument is the name of the JAR file containing
89 class and resource files for the application. The startup class must
90 be indicated by the Main-Class manifest header in its manifest file.
91 Arguments after the class file name or the JAR file name are passed to
93 the main() method.
94 javaw
96 Windows: The javaw command is identical to java, except that with javaw
97 there's no associated console window. Use javaw when you don't want a
98 command prompt window to appear. The javaw launcher will, however,
99 display a dialog box with error information if a launch fails.
100
102 To launch a class declared in a source file, run the java launcher in
103 source-file mode. Entering source-file mode is determined by two items
104 on the java command line:
105 • The first item on the command line that is not an option or part of
107 an option. In other words, the item in the command line that would
108 otherwise be the main class name.
109 • The --source version option, if present.
111 If the class identifies an existing file that has a .java extension, or
113 if the --source option is specified, then source-file mode is selected.
114 The source file is then compiled and run. The --source option can be
115 used to specify the source version or N of the source code. This de‐
116 termines the API that can be used. When you set --source N, you can
117 only use the public API that was defined in JDK N.
118 Note: The valid values of N change for each release, with new
120 values added and old values removed. You'll get an error mes‐
121 sage if you use a value of N that is no longer supported. The
122 supported values of N are the current Java SE release (17) and a
123 limited number of previous releases, detailed in the com‐
124 mand-line help for javac, under the --source and --release op‐
125 tions.
126 If the file does not have the .java extension, the --source option must
128 be used to tell the java command to use the source-file mode. The
129 --source option is used for cases when the source file is a "script" to
130 be executed and the name of the source file does not follow the normal
131 naming conventions for Java source files.
132 In source-file mode, the effect is as though the source file is com‐
134 piled into memory, and the first class found in the source file is exe‐
135 cuted. Any arguments placed after the name of the source file in the
136 original command line are passed to the compiled class when it is exe‐
137 cuted.
138 For example, if a file were named HelloWorld.java and contained a class
140 named hello.World, then the source-file mode command to launch the
141 class would be:
142 java HelloWorld.java
144 The example illustrates that the class can be in a named package, and
146 does not need to be in the unnamed package. This use of source-file
147 mode is informally equivalent to using the following two commands where
148 hello.World is the name of the class in the package:
149 javac -d <memory> HelloWorld.java
151 java -cp <memory> hello.World
152 In source-file mode, any additional command-line options are processed
154 as follows:
155 • The launcher scans the options specified before the source file for
157 any that are relevant in order to compile the source file.
158 This includes: --class-path, --module-path, --add-exports, --add-mod‐
160 ules, --limit-modules, --patch-module, --upgrade-module-path, and any
161 variant forms of those options. It also includes the new --en‐
162 able-preview option, described in JEP 12.
163 • No provision is made to pass any additional options to the compiler,
165 such as -processor or -Werror.
166 • Command-line argument files (@-files) may be used in the standard
168 way. Long lists of arguments for either the VM or the program being
169 invoked may be placed in files specified on the command-line by pre‐
170 fixing the filename with an @ character.
171 In source-file mode, compilation proceeds as follows:
173 • Any command-line options that are relevant to the compilation envi‐
175 ronment are taken into account.
176 • No other source files are found and compiled, as if the source path
178 is set to an empty value.
179 • Annotation processing is disabled, as if -proc:none is in effect.
181 • If a version is specified, via the --source option, the value is used
183 as the argument for an implicit --release option for the compilation.
184 This sets both the source version accepted by compiler and the system
185 API that may be used by the code in the source file.
186 • The source file is compiled in the context of an unnamed module.
188 • The source file should contain one or more top-level classes, the
190 first of which is taken as the class to be executed.
191 • The compiler does not enforce the optional restriction defined at the
193 end of JLS ??7.6, that a type in a named package should exist in a
194 file whose name is composed from the type name followed by the .java
195 extension.
196 • If the source file contains errors, appropriate error messages are
198 written to the standard error stream, and the launcher exits with a
199 non-zero exit code.
200 In source-file mode, execution proceeds as follows:
202 • The class to be executed is the first top-level class found in the
204 source file. It must contain a declaration of the standard pub‐
205 lic static void main(String[]) method.
206 • The compiled classes are loaded by a custom class loader, that dele‐
208 gates to the application class loader. This implies that classes ap‐
209 pearing on the application class path cannot refer to any classes de‐
210 clared in the source file.
211 • The compiled classes are executed in the context of an unnamed mod‐
213 ule, as though --add-modules=ALL-DEFAULT is in effect. This is in
214 addition to any other --add-module options that may be have been
215 specified on the command line.
216 • Any arguments appearing after the name of the file on the command
218 line are passed to the standard main method in the obvious way.
219 • It is an error if there is a class on the application class path
221 whose name is the same as that of the class to be executed.
222 See JEP 330: Launch Single-File Source-Code Programs [http://open‐
224 jdk.java.net/jeps/330] for complete details.
225
227 JDK_JAVA_OPTIONS prepends its content to the options parsed from the
228 command line. The content of the JDK_JAVA_OPTIONS environment variable
229 is a list of arguments separated by white-space characters (as deter‐
230 mined by isspace()). These are prepended to the command line arguments
231 passed to java launcher. The encoding requirement for the environment
232 variable is the same as the java command line on the system. JDK_JA‐
233 VA_OPTIONS environment variable content is treated in the same manner
234 as that specified in the command line.
235 Single (') or double (") quotes can be used to enclose arguments that
237 contain whitespace characters. All content between the open quote and
238 the first matching close quote are preserved by simply removing the
239 pair of quotes. In case a matching quote is not found, the launcher
240 will abort with an error message. @-files are supported as they are
241 specified in the command line. However, as in @-files, use of a wild‐
242 card is not supported. In order to mitigate potential misuse of
243 JDK_JAVA_OPTIONS behavior, options that specify the main class (such as
244 -jar) or cause the java launcher to exit without executing the main
245 class (such as -h) are disallowed in the environment variable. If any
246 of these options appear in the environment variable, the launcher will
247 abort with an error message. When JDK_JAVA_OPTIONS is set, the launch‐
248 er prints a message to stderr as a reminder.
249 Example:
251 $ export JDK_JAVA_OPTIONS='-g @file1 -Dprop=value @file2 -Dws.prop="white spaces"'
253 $ java -Xint @file3
254 is equivalent to the command line:
256 java -g @file1 -Dprop=value @file2 -Dws.prop="white spaces" -Xint @file3
258
260 The java command supports a wide range of options in the following cat‐
261 egories:
262 • Standard Options for Java: Options guaranteed to be supported by all
264 implementations of the Java Virtual Machine (JVM). They're used for
265 common actions, such as checking the version of the JRE, setting the
266 class path, enabling verbose output, and so on.
267 • Extra Options for Java: General purpose options that are specific to
269 the Java HotSpot Virtual Machine. They aren't guaranteed to be sup‐
270 ported by all JVM implementations, and are subject to change. These
271 options start with -X.
272 The advanced options aren't recommended for casual use. These are de‐
274 veloper options used for tuning specific areas of the Java HotSpot Vir‐
275 tual Machine operation that often have specific system requirements and
276 may require privileged access to system configuration parameters. Sev‐
277 eral examples of performance tuning are provided in Performance Tuning
278 Examples. These options aren't guaranteed to be supported by all JVM
279 implementations and are subject to change. Advanced options start with
280 -XX.
281 • Advanced Runtime Options for Java: Control the runtime behavior of
283 the Java HotSpot VM.
284 • Advanced JIT Compiler Options for java: Control the dynamic
286 just-in-time (JIT) compilation performed by the Java HotSpot VM.
287 • Advanced Serviceability Options for Java: Enable gathering system in‐
289 formation and performing extensive debugging.
290 • Advanced Garbage Collection Options for Java: Control how garbage
292 collection (GC) is performed by the Java HotSpot
293 Boolean options are used to either enable a feature that's disabled by
295 default or disable a feature that's enabled by default. Such options
296 don't require a parameter. Boolean -XX options are enabled using the
297 plus sign (-XX:+OptionName) and disabled using the minus sign (-XX:-Op‐
298 tionName).
299 For options that require an argument, the argument may be separated
301 from the option name by a space, a colon (:), or an equal sign (=), or
302 the argument may directly follow the option (the exact syntax differs
303 for each option). If you're expected to specify the size in bytes,
304 then you can use no suffix, or use the suffix k or K for kilobytes
305 (KB), m or M for megabytes (MB), or g or G for gigabytes (GB). For ex‐
306 ample, to set the size to 8 GB, you can specify either 8g, 8192m,
307 8388608k, or 8589934592 as the argument. If you are expected to speci‐
308 fy the percentage, then use a number from 0 to 1. For example, specify
309 0.25 for 25%.
310 The following sections describe the options that are obsolete, depre‐
312 cated, and removed:
313 • Deprecated Java Options: Accepted and acted upon --- a warning is is‐
315 sued when they're used.
316 • Obsolete Java Options: Accepted but ignored --- a warning is issued
318 when they're used.
319 • Removed Java Options: Removed --- using them results in an error.
321
323 These are the most commonly used options supported by all implementa‐
324 tions of the JVM.
325 Note: To specify an argument for a long option, you can use ei‐
327 ther --name=value or --name value.
328 -agentlib:libname[=options]
330 Loads the specified native agent library. After the library
331 name, a comma-separated list of options specific to the library
332 can be used.
333 • Linux and macOS: If the option -agentlib:foo is specified,
335 then the JVM attempts to load the library named libfoo.so in
336 the location specified by the LD_LIBRARY_PATH system variable
337 (on macOS this variable is DYLD_LIBRARY_PATH).
338 • Windows: If the option -agentlib:foo is specified, then the
340 JVM attempts to load the library named foo.dll in the location
341 specified by the PATH system variable.
342 The following example shows how to load the Java Debug Wire
344 Protocol (JDWP) library and listen for the socket connection
345 on port 8000, suspending the JVM before the main class loads:
346 -agentlib:jdwp=transport=dt_socket,server=y,ad‐
348 dress=8000
349 -agentpath:pathname[=options]
351 Loads the native agent library specified by the absolute path
352 name. This option is equivalent to -agentlib but uses the full
353 path and file name of the library.
354 --class-path classpath, -classpath classpath, or -cp classpath
356 A semicolon (;) separated list of directories, JAR archives, and
357 ZIP archives to search for class files.
358 Specifying classpath overrides any setting of the CLASSPATH en‐
360 vironment variable. If the class path option isn't used and
361 classpath isn't set, then the user class path consists of the
362 current directory (.).
363 As a special convenience, a class path element that contains a
365 base name of an asterisk (*) is considered equivalent to speci‐
366 fying a list of all the files in the directory with the exten‐
367 sion .jar or .JAR . A Java program can't tell the difference
368 between the two invocations. For example, if the directory my‐
369 dir contains a.jar and b.JAR, then the class path element my‐
370 dir/* is expanded to A.jar:b.JAR, except that the order of JAR
371 files is unspecified. All .jar files in the specified directo‐
372 ry, even hidden ones, are included in the list. A class path
373 entry consisting of an asterisk (*) expands to a list of all the
374 jar files in the current directory. The CLASSPATH environment
375 variable, where defined, is similarly expanded. Any class path
376 wildcard expansion that occurs before the Java VM is started.
377 Java programs never see wildcards that aren't expanded except by
378 querying the environment, such as by calling Sys‐
379 tem.getenv("CLASSPATH").
380 --disable-@files
382 Can be used anywhere on the command line, including in an argu‐
383 ment file, to prevent further @filename expansion. This option
384 stops expanding @-argfiles after the option.
385 --enable-preview
387 Allows classes to depend on preview features [https://docs.ora‐
388 cle.com/en/java/javase/12/language/index.html#JS‐
389 LAN-GUID-5A82FE0E-0CA4-4F1F-B075-564874FE2823] of the release.
390 --module-path modulepath... or -p modulepath
392 A semicolon (;) separated list of directories in which each di‐
393 rectory is a directory of modules.
394 --upgrade-module-path modulepath...
396 A semicolon (;) separated list of directories in which each di‐
397 rectory is a directory of modules that replace upgradeable mod‐
398 ules in the runtime image.
399 --add-modules module[,module...]
401 Specifies the root modules to resolve in addition to the initial
402 module. module also can be ALL-DEFAULT, ALL-SYSTEM, and
403 ALL-MODULE-PATH.
404 --list-modules
406 Lists the observable modules and then exits.
407 -d module_name or --describe-module module_name
409 Describes a specified module and then exits.
410 --dry-run
412 Creates the VM but doesn't execute the main method. This
413 --dry-run option might be useful for validating the command-line
414 options such as the module system configuration.
415 --validate-modules
417 Validates all modules and exit. This option is helpful for
418 finding conflicts and other errors with modules on the module
419 path.
420 -Dproperty=value
422 Sets a system property value. The property variable is a string
423 with no spaces that represents the name of the property. The
424 value variable is a string that represents the value of the
425 property. If value is a string with spaces, then enclose it in
426 quotation marks (for example -Dfoo="foo bar").
427 -disableassertions[:[packagename]...|:classname] or -da[:[package‐
429 name]...|:classname]
430 Disables assertions. By default, assertions are disabled in all
431 packages and classes. With no arguments, -disableassertions
432 (-da) disables assertions in all packages and classes. With the
433 packagename argument ending in ..., the switch disables asser‐
434 tions in the specified package and any subpackages. If the ar‐
435 gument is simply ..., then the switch disables assertions in the
436 unnamed package in the current working directory. With the
437 classname argument, the switch disables assertions in the speci‐
438 fied class.
439 The -disableassertions (-da) option applies to all class loaders
441 and to system classes (which don't have a class loader).
442 There's one exception to this rule: If the option is provided
443 with no arguments, then it doesn't apply to system classes.
444 This makes it easy to disable assertions in all classes except
445 for system classes. The -disablesystemassertions option enables
446 you to disable assertions in all system classes. To explicitly
447 enable assertions in specific packages or classes, use the -en‐
448 ableassertions (-ea) option. Both options can be used at the
449 same time. For example, to run the MyClass application with as‐
450 sertions enabled in the package com.wombat.fruitbat (and any
451 subpackages) but disabled in the class com.wombat.fruit‐
452 bat.Brickbat, use the following command:
453 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
455 bat.Brickbat MyClass
456 -disablesystemassertions or -dsa
458 Disables assertions in all system classes.
459 -enableassertions[:[packagename]...|:classname] or -ea[:[package‐
461 name]...|:classname]
462 Enables assertions. By default, assertions are disabled in all
463 packages and classes. With no arguments, -enableassertions
464 (-ea) enables assertions in all packages and classes. With the
465 packagename argument ending in ..., the switch enables asser‐
466 tions in the specified package and any subpackages. If the ar‐
467 gument is simply ..., then the switch enables assertions in the
468 unnamed package in the current working directory. With the
469 classname argument, the switch enables assertions in the speci‐
470 fied class.
471 The -enableassertions (-ea) option applies to all class loaders
473 and to system classes (which don't have a class loader).
474 There's one exception to this rule: If the option is provided
475 with no arguments, then it doesn't apply to system classes.
476 This makes it easy to enable assertions in all classes except
477 for system classes. The -enablesystemassertions option provides
478 a separate switch to enable assertions in all system classes.
479 To explicitly disable assertions in specific packages or class‐
480 es, use the -disableassertions (-da) option. If a single com‐
481 mand contains multiple instances of these switches, then they're
482 processed in order, before loading any classes. For example, to
483 run the MyClass application with assertions enabled only in the
484 package com.wombat.fruitbat (and any subpackages) but disabled
485 in the class com.wombat.fruitbat.Brickbat, use the following
486 command:
487 java -ea:com.wombat.fruitbat... -da:com.wombat.fruit‐
489 bat.Brickbat MyClass
490 -enablesystemassertions or -esa
492 Enables assertions in all system classes.
493 -help, -h, or -?
495 Prints the help message to the error stream.
496 --help Prints the help message to the output stream.
498 -javaagent:jarpath[=options]
500 Loads the specified Java programming language agent. See ja‐
501 va.lang.instrument.
502 --show-version
504 Prints the product version to the output stream and continues.
505 -showversion
507 Prints the product version to the error stream and continues.
508 --show-module-resolution
510 Shows module resolution output during startup.
511 -splash:imagepath
513 Shows the splash screen with the image specified by imagepath.
514 HiDPI scaled images are automatically supported and used if
515 available. The unscaled image file name, such as image.ext,
516 should always be passed as the argument to the -splash option.
517 The most appropriate scaled image provided is picked up automat‐
518 ically.
519 For example, to show the splash.gif file from the images direc‐
521 tory when starting your application, use the following option:
522 -splash:images/splash.gif
524 See the SplashScreen API documentation for more information.
526 -verbose:class
528 Displays information about each loaded class.
529 -verbose:gc
531 Displays information about each garbage collection (GC) event.
532 -verbose:jni
534 Displays information about the use of native methods and other
535 Java Native Interface (JNI) activity.
536 -verbose:module
538 Displays information about the modules in use.
539 --version
541 Prints product version to the output stream and exits.
542 -version
544 Prints product version to the error stream and exits.
545 -X Prints the help on extra options to the error stream.
547 --help-extra
549 Prints the help on extra options to the output stream.
550 @argfile
552 Specifies one or more argument files prefixed by @ used by the
553 java command. It isn't uncommon for the java command line to be
554 very long because of the .jar files needed in the classpath.
555 The @argfile option overcomes command-line length limitations by
556 enabling the launcher to expand the contents of argument files
557 after shell expansion, but before argument processing. Contents
558 in the argument files are expanded because otherwise, they would
559 be specified on the command line until the --disable-@files op‐
560 tion was encountered.
561 The argument files can also contain the main class name and all
563 options. If an argument file contains all of the options re‐
564 quired by the java command, then the command line could simply
565 be:
566 java @argfile
568 See java Command-Line Argument Files for a description and exam‐
570 ples of using @-argfiles.
571
573 The following java options are general purpose options that are specif‐
574 ic to the Java HotSpot Virtual Machine.
575 -Xbatch
577 Disables background compilation. By default, the JVM compiles
578 the method as a background task, running the method in inter‐
579 preter mode until the background compilation is finished. The
580 -Xbatch flag disables background compilation so that compilation
581 of all methods proceeds as a foreground task until completed.
582 This option is equivalent to -XX:-BackgroundCompilation.
583 -Xbootclasspath/a:directories|zip|JAR-files
585 Specifies a list of directories, JAR files, and ZIP archives to
586 append to the end of the default bootstrap class path.
587 Linux and macOS: Colons (:) separate entities in this list.
589 Windows: Semicolons (;) separate entities in this list.
591 -Xcheck:jni
593 Performs additional checks for Java Native Interface (JNI) func‐
594 tions.
595 The following checks are considered indicative of significant
597 problems with the native code, and the JVM terminates with an
598 irrecoverable error in such cases:
599 • The thread doing the call is not attached to the JVM.
601 • The thread doing the call is using the JNIEnv belonging to an‐
603 other thread.
604 • A parameter validation check fails:
606 • A jfieldID, or jmethodID, is detected as being invalid. For
608 example:
609 • Of the wrong type
611 • Associated with the wrong class
613 • A parameter of the wrong type is detected.
615 • An invalid parameter value is detected. For example:
617 • NULL where not permitted
619 • An out-of-bounds array index, or frame capacity
621 • A non-UTF-8 string
623 • An invalid JNI reference
625 • An attempt to use a ReleaseXXX function on a parameter not
627 produced by the corresponding GetXXX function
628 The following checks only result in warnings being printed:
630 • A JNI call was made without checking for a pending exception
632 from a previous JNI call, and the current call is not safe
633 when an exception may be pending.
634 • The number of JNI local references existing when a JNI func‐
636 tion terminates exceeds the number guaranteed to be available.
637 See the EnsureLocalcapacity function.
638 • A class descriptor is in decorated format (Lname;) when it
640 should not be.
641 • A NULL parameter is allowed, but its use is questionable.
643 • Calling other JNI functions in the scope of Get/ReleasePrimi‐
645 tiveArrayCritical or Get/ReleaseStringCritical
646 Expect a performance degradation when this option is used.
648 -Xdebug
650 Does nothing. Provided for backward compatibility.
651 -Xdiag Shows additional diagnostic messages.
653 -Xint Runs the application in interpreted-only mode. Compilation to
655 native code is disabled, and all bytecode is executed by the in‐
656 terpreter. The performance benefits offered by the just-in-time
657 (JIT) compiler aren't present in this mode.
658 -Xinternalversion
660 Displays more detailed JVM version information than the -version
661 option, and then exits.
662 -Xlog:option
664 Configure or enable logging with the Java Virtual Machine (JVM)
665 unified logging framework. See Enable Logging with the JVM Uni‐
666 fied Logging Framework.
667 -Xmixed
669 Executes all bytecode by the interpreter except for hot methods,
670 which are compiled to native code. On by default. Use -Xint to
671 switch off.
672 -Xmn size
674 Sets the initial and maximum size (in bytes) of the heap for the
675 young generation (nursery) in the generational collectors. Ap‐
676 pend the letter k or K to indicate kilobytes, m or M to indicate
677 megabytes, or g or G to indicate gigabytes. The young genera‐
678 tion region of the heap is used for new objects. GC is per‐
679 formed in this region more often than in other regions. If the
680 size for the young generation is too small, then a lot of minor
681 garbage collections are performed. If the size is too large,
682 then only full garbage collections are performed, which can take
683 a long time to complete. It is recommended that you do not set
684 the size for the young generation for the G1 collector, and keep
685 the size for the young generation greater than 25% and less than
686 50% of the overall heap size for other collectors. The follow‐
687 ing examples show how to set the initial and maximum size of
688 young generation to 256 MB using various units:
689 -Xmn256m
691 -Xmn262144k
692 -Xmn268435456
693 Instead of the -Xmn option to set both the initial and maximum
695 size of the heap for the young generation, you can use -XX:New‐
696 Size to set the initial size and -XX:MaxNewSize to set the maxi‐
697 mum size.
698 -Xms size
700 Sets the minimum and initial size (in bytes) of the heap. This
701 value must be a multiple of 1024 and greater than 1 MB. Append
702 the letter k or K to indicate kilobytes, m or M to indicate
703 megabytes, g or G to indicate gigabytes. The following examples
704 show how to set the size of allocated memory to 6 MB using vari‐
705 ous units:
706 -Xms6291456
708 -Xms6144k
709 -Xms6m
710 Instead of the -Xms option to set both the minimum and initial
712 size of the heap, you can use -XX:MinHeapSize to set the minimum
713 size and -XX:InitialHeapSize to set the initial size.
714 If you don't set this option, the initial size is set as the sum
716 of the sizes allocated for the old generation and the young gen‐
717 eration. The initial size of the heap for the young generation
718 can be set using the -Xmn option or the -XX:NewSize option.
719 -Xmx size
721 Specifies the maximum size (in bytes) of the heap. This value
722 must be a multiple of 1024 and greater than 2 MB. Append the
723 letter k or K to indicate kilobytes, m or M to indicate
724 megabytes, or g or G to indicate gigabytes. The default value
725 is chosen at runtime based on system configuration. For server
726 deployments, -Xms and -Xmx are often set to the same value. The
727 following examples show how to set the maximum allowed size of
728 allocated memory to 80 MB using various units:
729 -Xmx83886080
731 -Xmx81920k
732 -Xmx80m
733 The -Xmx option is equivalent to -XX:MaxHeapSize.
735 -Xnoclassgc
737 Disables garbage collection (GC) of classes. This can save some
738 GC time, which shortens interruptions during the application
739 run. When you specify -Xnoclassgc at startup, the class objects
740 in the application are left untouched during GC and are always
741 be considered live. This can result in more memory being perma‐
742 nently occupied which, if not used carefully, throws an
743 out-of-memory exception.
744 -Xrs Reduces the use of operating system signals by the JVM. Shut‐
746 down hooks enable the orderly shutdown of a Java application by
747 running user cleanup code (such as closing database connections)
748 at shutdown, even if the JVM terminates abruptly.
749 • Linux and macOS:
751 • The JVM catches signals to implement shutdown hooks for un‐
753 expected termination. The JVM uses SIGHUP, SIGINT, and
754 SIGTERM to initiate the running of shutdown hooks.
755 • Applications embedding the JVM frequently need to trap sig‐
757 nals such as SIGINT or SIGTERM, which can lead to interfer‐
758 ence with the JVM signal handlers. The -Xrs option is
759 available to address this issue. When -Xrs is used, the
760 signal masks for SIGINT, SIGTERM, SIGHUP, and SIGQUIT aren't
761 changed by the JVM, and signal handlers for these signals
762 aren't installed.
763 • Windows:
765 • The JVM watches for console control events to implement
767 shutdown hooks for unexpected termination. Specifically,
768 the JVM registers a console control handler that begins
769 shutdown-hook processing and returns TRUE for CTRL_C_EVENT,
770 CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUT‐
771 DOWN_EVENT.
772 • The JVM uses a similar mechanism to implement the feature of
774 dumping thread stacks for debugging purposes. The JVM uses
775 CTRL_BREAK_EVENT to perform thread dumps.
776 • If the JVM is run as a service (for example, as a servlet
778 engine for a web server), then it can receive CTRL_LO‐
779 GOFF_EVENT but shouldn't initiate shutdown because the oper‐
780 ating system doesn't actually terminate the process. To
781 avoid possible interference such as this, the -Xrs option
782 can be used. When the -Xrs option is used, the JVM doesn't
783 install a console control handler, implying that it doesn't
784 watch for or process CTRL_C_EVENT, CTRL_CLOSE_EVENT,
785 CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.
786 There are two consequences of specifying -Xrs:
788 • Linux and macOS: SIGQUIT thread dumps aren't available.
790 • Windows: Ctrl + Break thread dumps aren't available.
792 User code is responsible for causing shutdown hooks to run, for
794 example, by calling the System.exit() when the JVM is to be ter‐
795 minated.
796 -Xshare:mode
798 Sets the class data sharing (CDS) mode.
799 Possible mode arguments for this option include the following:
801 auto Use shared class data if possible (default).
803 on Require using shared class data, otherwise fail.
805 Note: The -Xshare:on option is used for testing purposes
807 only. It may cause the VM to unexpectedly exit during
808 start-up when the CDS archive cannot be used (for exam‐
809 ple, when certain VM parameters are changed, or when a
810 different JDK is used). This option should not be used
811 in production environments.
812 off Do not attempt to use shared class data.
814 -XshowSettings
816 Shows all settings and then continues.
817 -XshowSettings:category
819 Shows settings and continues. Possible category arguments for
820 this option include the following:
821 all Shows all categories of settings. This is the default
823 value.
824 locale Shows settings related to locale.
826 properties
828 Shows settings related to system properties.
829 vm Shows the settings of the JVM.
831 system Linux: Shows host system or container configuration and
833 continues.
834 -Xss size
836 Sets the thread stack size (in bytes). Append the letter k or K
837 to indicate KB, m or M to indicate MB, or g or G to indicate GB.
838 The default value depends on the platform:
839 • Linux/x64 (64-bit): 1024 KB
841 • macOS (64-bit): 1024 KB
843 • Windows: The default value depends on virtual memory
845 The following examples set the thread stack size to 1024 KB in
847 different units:
848 -Xss1m
850 -Xss1024k
851 -Xss1048576
852 This option is similar to -XX:ThreadStackSize.
854 --add-reads module=target-module(,target-module)*
856 Updates module to read the target-module, regardless of the mod‐
857 ule declaration. target-module can be all unnamed to read all
858 unnamed modules.
859 --add-exports module/package=target-module(,target-module)*
861 Updates module to export package to target-module, regardless of
862 module declaration. The target-module can be all unnamed to ex‐
863 port to all unnamed modules.
864 --add-opens module/package=target-module(,target-module)*
866 Updates module to open package to target-module, regardless of
867 module declaration.
868 --limit-modules module[,module...]
870 Specifies the limit of the universe of observable modules.
871 --patch-module module=file(;file)*
873 Overrides or augments a module with classes and resources in JAR
874 files or directories.
875 --source version
877 Sets the version of the source in source-file mode.
878
880 The following extra options are macOS specific.
881 -XstartOnFirstThread
883 Runs the main() method on the first (AppKit) thread.
884 -Xdock:name=application_name
886 Overrides the default application name displayed in dock.
887 -Xdock:icon=path_to_icon_file
889 Overrides the default icon displayed in dock.
890
892 These java options can be used to enable other advanced options.
893 -XX:+UnlockDiagnosticVMOptions
895 Unlocks the options intended for diagnosing the JVM. By de‐
896 fault, this option is disabled and diagnostic options aren't
897 available.
898 Command line options that are enabled with the use of this op‐
900 tion are not supported. If you encounter issues while using any
901 of these options, it is very likely that you will be required to
902 reproduce the problem without using any of these unsupported op‐
903 tions before Oracle Support can assist with an investigation.
904 It is also possible that any of these options may be removed or
905 their behavior changed without any warning.
906 -XX:+UnlockExperimentalVMOptions
908 Unlocks the options that provide experimental features in the
909 JVM. By default, this option is disabled and experimental fea‐
910 tures aren't available.
911
913 These java options control the runtime behavior of the Java HotSpot VM.
914 -XX:ActiveProcessorCount=x
916 Overrides the number of CPUs that the VM will use to calculate
917 the size of thread pools it will use for various operations such
918 as Garbage Collection and ForkJoinPool.
919 The VM normally determines the number of available processors
921 from the operating system. This flag can be useful for parti‐
922 tioning CPU resources when running multiple Java processes in
923 docker containers. This flag is honored even if UseContainer‐
924 Support is not enabled. See -XX:-UseContainerSupport for a de‐
925 scription of enabling and disabling container support.
926 -XX:AllocateHeapAt=path
928 Takes a path to the file system and uses memory mapping to allo‐
929 cate the object heap on the memory device. Using this option
930 enables the HotSpot VM to allocate the Java object heap on an
931 alternative memory device, such as an NV-DIMM, specified by the
932 user.
933 Alternative memory devices that have the same semantics as DRAM,
935 including the semantics of atomic operations, can be used in‐
936 stead of DRAM for the object heap without changing the existing
937 application code. All other memory structures (such as the code
938 heap, metaspace, and thread stacks) continue to reside in DRAM.
939 Some operating systems expose non-DRAM memory through the file
941 system. Memory-mapped files in these file systems bypass the
942 page cache and provide a direct mapping of virtual memory to the
943 physical memory on the device. The existing heap related flags
944 (such as -Xmx and -Xms) and garbage-collection related flags
945 continue to work as before.
946 -XX:-CompactStrings
948 Disables the Compact Strings feature. By default, this option
949 is enabled. When this option is enabled, Java Strings contain‐
950 ing only single-byte characters are internally represented and
951 stored as single-byte-per-character Strings using ISO-8859-1 /
952 Latin-1 encoding. This reduces, by 50%, the amount of space re‐
953 quired for Strings containing only single-byte characters. For
954 Java Strings containing at least one multibyte character: these
955 are represented and stored as 2 bytes per character using UTF-16
956 encoding. Disabling the Compact Strings feature forces the use
957 of UTF-16 encoding as the internal representation for all Java
958 Strings.
959 Cases where it may be beneficial to disable Compact Strings in‐
961 clude the following:
962 • When it's known that an application overwhelmingly will be al‐
964 locating multibyte character Strings
965 • In the unexpected event where a performance regression is ob‐
967 served in migrating from Java SE 8 to Java SE 9 and an analy‐
968 sis shows that Compact Strings introduces the regression
969 In both of these scenarios, disabling Compact Strings makes
971 sense.
972 -XX:ErrorFile=filename
974 Specifies the path and file name to which error data is written
975 when an irrecoverable error occurs. By default, this file is
976 created in the current working directory and named hs_err_pid‐
977 pid.log where pid is the identifier of the process that encoun‐
978 tered the error.
979 The following example shows how to set the default log file
981 (note that the identifier of the process is specified as %p):
982 -XX:ErrorFile=./hs_err_pid%p.log
984 • Linux and macOS: The following example shows how to set the
986 error log to /var/log/java/java_error.log:
987 -XX:ErrorFile=/var/log/java/java_error.log
989 • Windows: The following example shows how to set the error log
991 file to C:/log/java/java_error.log:
992 -XX:ErrorFile=C:/log/java/java_error.log
994 If the file exists, and is writeable, then it will be overwrit‐
996 ten. Otherwise, if the file can't be created in the specified
997 directory (due to insufficient space, permission problem, or an‐
998 other issue), then the file is created in the temporary directo‐
999 ry for the operating system:
1000 • Linux and macOS: The temporary directory is /tmp.
1002 • Windows: The temporary directory is specified by the value of
1004 the TMP environment variable; if that environment variable
1005 isn't defined, then the value of the TEMP environment variable
1006 is used.
1007 -XX:+ExtensiveErrorReports
1009 Enables the reporting of more extensive error information in the
1010 ErrorFile. This option can be turned on in environments where
1011 maximal information is desired - even if the resulting logs may
1012 be quite large and/or contain information that might be consid‐
1013 ered sensitive. The information can vary from release to re‐
1014 lease, and across different platforms. By default this option
1015 is disabled.
1016 -XX:FlightRecorderOptions=parameter=value (or)-XX:FlightRecorderOp‐
1018 tions:parameter=value
1019 Sets the parameters that control the behavior of JFR.
1020 The following list contains the available JFR parameter=value
1022 entries:
1023 globalbuffersize=size
1025 Specifies the total amount of primary memory used for da‐
1026 ta retention. The default value is based on the value
1027 specified for memorysize. Change the memorysize parame‐
1028 ter to alter the size of global buffers.
1029 maxchunksize=size
1031 Specifies the maximum size (in bytes) of the data chunks
1032 in a recording. Append m or M to specify the size in
1033 megabytes (MB), or g or G to specify the size in giga‐
1034 bytes (GB). By default, the maximum size of data chunks
1035 is set to 12 MB. The minimum allowed is 1 MB.
1036 memorysize=size
1038 Determines how much buffer memory should be used, and
1039 sets the globalbuffersize and numglobalbuffers parameters
1040 based on the size specified. Append m or M to specify
1041 the size in megabytes (MB), or g or G to specify the size
1042 in gigabytes (GB). By default, the memory size is set to
1043 10 MB.
1044 numglobalbuffers
1046 Specifies the number of global buffers used. The default
1047 value is based on the memory size specified. Change the
1048 memorysize parameter to alter the number of global buf‐
1049 fers.
1050 old-object-queue-size=number-of-objects
1052 Maximum number of old objects to track. By default, the
1053 number of objects is set to 256.
1054 repository=path
1056 Specifies the repository (a directory) for temporary disk
1057 storage. By default, the system's temporary directory is
1058 used.
1059 retransform={true|false}
1061 Specifies whether event classes should be retransformed
1062 using JVMTI. If false, instrumentation is added when
1063 event classes are loaded. By default, this parameter is
1064 enabled.
1065 samplethreads={true|false}
1067 Specifies whether thread sampling is enabled. Thread
1068 sampling occurs only if the sampling event is enabled
1069 along with this parameter. By default, this parameter is
1070 enabled.
1071 stackdepth=depth
1073 Stack depth for stack traces. By default, the depth is
1074 set to 64 method calls. The maximum is 2048. Values
1075 greater than 64 could create significant overhead and re‐
1076 duce performance.
1077 threadbuffersize=size
1079 Specifies the per-thread local buffer size (in bytes).
1080 By default, the local buffer size is set to 8 kilobytes,
1081 with a minimum value of 4 kilobytes. Overriding this pa‐
1082 rameter could reduce performance and is not recommended.
1083 You can specify values for multiple parameters by separating
1085 them with a comma.
1086 -XX:LargePageSizeInBytes=size
1088 Sets the maximum large page size (in bytes) used by the JVM.
1089 The size argument must be a valid page size supported by the en‐
1090 vironment to have any effect. Append the letter k or K to indi‐
1091 cate kilobytes, m or M to indicate megabytes, or g or G to indi‐
1092 cate gigabytes. By default, the size is set to 0, meaning that
1093 the JVM will use the default large page size for the environment
1094 as the maximum size for large pages. See Large Pages.
1095 The following example describes how to set the large page size
1097 to 1 gigabyte (GB):
1098 -XX:LargePageSizeInBytes=1g
1100 -XX:MaxDirectMemorySize=size
1102 Sets the maximum total size (in bytes) of the java.nio package,
1103 direct-buffer allocations. Append the letter k or K to indicate
1104 kilobytes, m or M to indicate megabytes, or g or G to indicate
1105 gigabytes. By default, the size is set to 0, meaning that the
1106 JVM chooses the size for NIO direct-buffer allocations automati‐
1107 cally.
1108 The following examples illustrate how to set the NIO size to
1110 1024 KB in different units:
1111 -XX:MaxDirectMemorySize=1m
1113 -XX:MaxDirectMemorySize=1024k
1114 -XX:MaxDirectMemorySize=1048576
1115 -XX:-MaxFDLimit
1117 Disables the attempt to set the soft limit for the number of
1118 open file descriptors to the hard limit. By default, this op‐
1119 tion is enabled on all platforms, but is ignored on Windows.
1120 The only time that you may need to disable this is on Mac OS,
1121 where its use imposes a maximum of 10240, which is lower than
1122 the actual system maximum.
1123 -XX:NativeMemoryTracking=mode
1125 Specifies the mode for tracking JVM native memory usage. Possi‐
1126 ble mode arguments for this option include the following:
1127 off Instructs not to track JVM native memory usage. This is
1129 the default behavior if you don't specify the -XX:Native‐
1130 MemoryTracking option.
1131 summary
1133 Tracks memory usage only by JVM subsystems, such as Java
1134 heap, class, code, and thread.
1135 detail In addition to tracking memory usage by JVM subsystems,
1137 track memory usage by individual CallSite, individual
1138 virtual memory region and its committed regions.
1139 -XX:ObjectAlignmentInBytes=alignment
1141 Sets the memory alignment of Java objects (in bytes). By de‐
1142 fault, the value is set to 8 bytes. The specified value should
1143 be a power of 2, and must be within the range of 8 and 256 (in‐
1144 clusive). This option makes it possible to use compressed
1145 pointers with large Java heap sizes.
1146 The heap size limit in bytes is calculated as:
1148 4GB * ObjectAlignmentInBytes
1150 Note: As the alignment value increases, the unused space
1152 between objects also increases. As a result, you may not
1153 realize any benefits from using compressed pointers with
1154 large Java heap sizes.
1155 -XX:OnError=string
1157 Sets a custom command or a series of semicolon-separated com‐
1158 mands to run when an irrecoverable error occurs. If the string
1159 contains spaces, then it must be enclosed in quotation marks.
1160 • Linux and macOS: The following example shows how the -XX:On‐
1162 Error option can be used to run the gcore command to create a
1163 core image, and start the gdb debugger to attach to the
1164 process in case of an irrecoverable error (the %p designates
1165 the current process identifier):
1166 -XX:OnError="gcore %p;gdb -p %p"
1168 • Windows: The following example shows how the -XX:OnError op‐
1170 tion can be used to run the userdump.exe utility to obtain a
1171 crash dump in case of an irrecoverable error (the %p desig‐
1172 nates the current process identifier). This example assumes
1173 that the path to the userdump.exe utility is specified in the
1174 PATH environment variable:
1175 -XX:OnError="userdump.exe %p"
1177 -XX:OnOutOfMemoryError=string
1179 Sets a custom command or a series of semicolon-separated com‐
1180 mands to run when an OutOfMemoryError exception is first thrown.
1181 If the string contains spaces, then it must be enclosed in quo‐
1182 tation marks. For an example of a command string, see the de‐
1183 scription of the -XX:OnError option.
1184 -XX:+PrintCommandLineFlags
1186 Enables printing of ergonomically selected JVM flags that ap‐
1187 peared on the command line. It can be useful to know the ergo‐
1188 nomic values set by the JVM, such as the heap space size and the
1189 selected garbage collector. By default, this option is disabled
1190 and flags aren't printed.
1191 -XX:+PreserveFramePointer
1193 Selects between using the RBP register as a general purpose reg‐
1194 ister (-XX:-PreserveFramePointer) and using the RBP register to
1195 hold the frame pointer of the currently executing method
1196 (-XX:+PreserveFramePointer . If the frame pointer is available,
1197 then external profiling tools (for example, Linux perf) can con‐
1198 struct more accurate stack traces.
1199 -XX:+PrintNMTStatistics
1201 Enables printing of collected native memory tracking data at JVM
1202 exit when native memory tracking is enabled (see -XX:NativeMemo‐
1203 ryTracking). By default, this option is disabled and native
1204 memory tracking data isn't printed.
1205 -XX:SharedArchiveFile=path
1207 Specifies the path and name of the class data sharing (CDS) ar‐
1208 chive file
1209 See Application Class Data Sharing.
1211 -XX:SharedArchiveConfigFile=shared_config_file
1213 Specifies additional shared data added to the archive file.
1214 -XX:SharedClassListFile=file_name
1216 Specifies the text file that contains the names of the classes
1217 to store in the class data sharing (CDS) archive. This file
1218 contains the full name of one class per line, except slashes (/)
1219 replace dots (.). For example, to specify the classes ja‐
1220 va.lang.Object and hello.Main, create a text file that contains
1221 the following two lines:
1222 java/lang/Object
1224 hello/Main
1225 The classes that you specify in this text file should include
1227 the classes that are commonly used by the application. They may
1228 include any classes from the application, extension, or boot‐
1229 strap class paths.
1230 See Application Class Data Sharing.
1232 -XX:+ShowCodeDetailsInExceptionMessages
1234 Enables printing of improved NullPointerException messages.
1235 When an application throws a NullPointerException, the option
1236 enables the JVM to analyze the program's bytecode instructions
1237 to determine precisely which reference is null, and describes
1238 the source with a null-detail message. The null-detail message
1239 is calculated and returned by NullPointerException.getMessage(),
1240 and will be printed as the exception message along with the
1241 method, filename, and line number. By default, this option is
1242 enabled.
1243 -XX:+ShowMessageBoxOnError
1245 Enables the display of a dialog box when the JVM experiences an
1246 irrecoverable error. This prevents the JVM from exiting and
1247 keeps the process active so that you can attach a debugger to it
1248 to investigate the cause of the error. By default, this option
1249 is disabled.
1250 -XX:StartFlightRecording=parameter=value
1252 Starts a JFR recording for the Java application. This option is
1253 equivalent to the JFR.start diagnostic command that starts a
1254 recording during runtime. You can set the following parame‐
1255 ter=value entries when starting a JFR recording:
1256 delay=time
1258 Specifies the delay between the Java application launch
1259 time and the start of the recording. Append s to specify
1260 the time in seconds, m for minutes, h for hours, or d for
1261 days (for example, specifying 10m means 10 minutes). By
1262 default, there's no delay, and this parameter is set to
1263 0.
1264 disk={true|false}
1266 Specifies whether to write data to disk while recording.
1267 By default, this parameter is enabled.
1268 dumponexit={true|false}
1270 Specifies if the running recording is dumped when the JVM
1271 shuts down. If enabled and a filename is not entered,
1272 the recording is written to a file in the directory where
1273 the process was started. The file name is a system-gen‐
1274 erated name that contains the process ID, recording ID,
1275 and current timestamp, similar to
1276 hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By de‐
1277 fault, this parameter is disabled.
1278 duration=time
1280 Specifies the duration of the recording. Append s to
1281 specify the time in seconds, m for minutes, h for hours,
1282 or d for days (for example, specifying 5h means 5 hours).
1283 By default, the duration isn't limited, and this parame‐
1284 ter is set to 0.
1285 filename=path
1287 Specifies the path and name of the file to which the
1288 recording is written when the recording is stopped, for
1289 example:
1290 • recording.jfr
1292 • /home/user/recordings/recording.jfr
1294 • c:\recordings\recording.jfr
1296 name=identifier
1298 Takes both the name and the identifier of a recording.
1299 maxage=time
1301 Specifies the maximum age of disk data to keep for the
1302 recording. This parameter is valid only when the disk
1303 parameter is set to true. Append s to specify the time
1304 in seconds, m for minutes, h for hours, or d for days
1305 (for example, specifying 30s means 30 seconds). By de‐
1306 fault, the maximum age isn't limited, and this parameter
1307 is set to 0s.
1308 maxsize=size
1310 Specifies the maximum size (in bytes) of disk data to
1311 keep for the recording. This parameter is valid only
1312 when the disk parameter is set to true. The value must
1313 not be less than the value for the maxchunksize parameter
1314 set with -XX:FlightRecorderOptions. Append m or M to
1315 specify the size in megabytes, or g or G to specify the
1316 size in gigabytes. By default, the maximum size of disk
1317 data isn't limited, and this parameter is set to 0.
1318 path-to-gc-roots={true|false}
1320 Specifies whether to collect the path to garbage collec‐
1321 tion (GC) roots at the end of a recording. By default,
1322 this parameter is disabled.
1323 The path to GC roots is useful for finding memory leaks,
1325 but collecting it is time-consuming. Enable this option
1326 only when you start a recording for an application that
1327 you suspect has a memory leak. If the settings parameter
1328 is set to profile, the stack trace from where the poten‐
1329 tial leaking object was allocated is included in the in‐
1330 formation collected.
1331 settings=path
1333 Specifies the path and name of the event settings file
1334 (of type JFC). By default, the default.jfc file is used,
1335 which is located in JAVA_HOME/lib/jfr. This default set‐
1336 tings file collects a predefined set of information with
1337 low overhead, so it has minimal impact on performance and
1338 can be used with recordings that run continuously.
1339 A second settings file is also provided, profile.jfc,
1341 which provides more data than the default configuration,
1342 but can have more overhead and impact performance. Use
1343 this configuration for short periods of time when more
1344 information is needed.
1345 You can specify values for multiple parameters by separating
1347 them with a comma. Event settings and .jfc options can be spec‐
1348 ified using the following syntax:
1349 option=value
1351 Specifies the option value to modify. To list available
1352 options, use the JAVA_HOME/bin/jfr tool.
1353 event-setting=value
1355 Specifies the event setting value to modify. Use the
1356 form: #= To add a new event setting, prefix the event
1357 name with '+'.
1358 You can specify values for multiple event settings and .jfc op‐
1360 tions by separating them with a comma. In case of a conflict
1361 between a parameter and a .jfc option, the parameter will take
1362 precedence. The whitespace delimiter can be omitted for times‐
1363 pan values, i.e. 20ms. For more information about the settings
1364 syntax, see Javadoc of the jdk.jfr package.
1365 -XX:ThreadStackSize=size
1367 Sets the Java thread stack size (in kilobytes). Use of a scal‐
1368 ing suffix, such as k, results in the scaling of the kilobytes
1369 value so that -XX:ThreadStackSize=1k sets the Java thread stack
1370 size to 1024*1024 bytes or 1 megabyte. The default value de‐
1371 pends on the platform:
1372 • Linux/x64 (64-bit): 1024 KB
1374 • macOS (64-bit): 1024 KB
1376 • Windows: The default value depends on virtual memory
1378 The following examples show how to set the thread stack size to
1380 1 megabyte in different units:
1381 -XX:ThreadStackSize=1k
1383 -XX:ThreadStackSize=1024
1384 This option is similar to -Xss.
1386 -XX:-UseCompressedOops
1388 Disables the use of compressed pointers. By default, this op‐
1389 tion is enabled, and compressed pointers are used. This will
1390 automatically limit the maximum ergonomically determined Java
1391 heap size to the maximum amount of memory that can be covered by
1392 compressed pointers. By default this range is 32 GB.
1393 With compressed oops enabled, object references are represented
1395 as 32-bit offsets instead of 64-bit pointers, which typically
1396 increases performance when running the application with Java
1397 heap sizes smaller than the compressed oops pointer range. This
1398 option works only for 64-bit JVMs.
1399 It's possible to use compressed pointers with Java heap sizes
1401 greater than 32 GB. See the -XX:ObjectAlignmentInBytes option.
1402 -XX:-UseContainerSupport
1404 The VM now provides automatic container detection support, which
1405 allows the VM to determine the amount of memory and number of
1406 processors that are available to a Java process running in dock‐
1407 er containers. It uses this information to allocate system re‐
1408 sources. This support is only available on Linux x64 platforms.
1409 If supported, the default for this flag is true, and container
1410 support is enabled by default. It can be disabled with
1411 -XX:-UseContainerSupport.
1412 Unified Logging is available to help to diagnose issues related
1414 to this support.
1415 Use -Xlog:os+container=trace for maximum logging of container
1417 information. See Enable Logging with the JVM Unified Logging
1418 Framework for a description of using Unified Logging.
1419 -XX:+UseHugeTLBFS
1421 Linux only: This option is the equivalent of specifying
1422 -XX:+UseLargePages. This option is disabled by default. This
1423 option pre-allocates all large pages up-front, when memory is
1424 reserved; consequently the JVM can't dynamically grow or shrink
1425 large pages memory areas; see -XX:UseTransparentHugePages if you
1426 want this behavior.
1427 See Large Pages.
1429 -XX:+UseLargePages
1431 Enables the use of large page memory. By default, this option
1432 is disabled and large page memory isn't used.
1433 See Large Pages.
1435 -XX:+UseTransparentHugePages
1437 Linux only: Enables the use of large pages that can dynamically
1438 grow or shrink. This option is disabled by default. You may
1439 encounter performance problems with transparent huge pages as
1440 the OS moves other pages around to create huge pages; this op‐
1441 tion is made available for experimentation.
1442 -XX:+AllowUserSignalHandlers
1444 Enables installation of signal handlers by the application. By
1445 default, this option is disabled and the application isn't al‐
1446 lowed to install signal handlers.
1447 -XX:VMOptionsFile=filename
1449 Allows user to specify VM options in a file, for example, ja‐
1450 va -XX:VMOptionsFile=/var/my_vm_options HelloWorld.
1451
1453 These java options control the dynamic just-in-time (JIT) compilation
1454 performed by the Java HotSpot VM.
1455 -XX:AllocateInstancePrefetchLines=lines
1457 Sets the number of lines to prefetch ahead of the instance allo‐
1458 cation pointer. By default, the number of lines to prefetch is
1459 set to 1:
1460 -XX:AllocateInstancePrefetchLines=1
1462 -XX:AllocatePrefetchDistance=size
1464 Sets the size (in bytes) of the prefetch distance for object al‐
1465 location. Memory about to be written with the value of new ob‐
1466 jects is prefetched up to this distance starting from the ad‐
1467 dress of the last allocated object. Each Java thread has its
1468 own allocation point.
1469 Negative values denote that prefetch distance is chosen based on
1471 the platform. Positive values are bytes to prefetch. Append
1472 the letter k or K to indicate kilobytes, m or M to indicate
1473 megabytes, or g or G to indicate gigabytes. The default value
1474 is set to -1.
1475 The following example shows how to set the prefetch distance to
1477 1024 bytes:
1478 -XX:AllocatePrefetchDistance=1024
1480 -XX:AllocatePrefetchInstr=instruction
1482 Sets the prefetch instruction to prefetch ahead of the alloca‐
1483 tion pointer. Possible values are from 0 to 3. The actual in‐
1484 structions behind the values depend on the platform. By de‐
1485 fault, the prefetch instruction is set to 0:
1486 -XX:AllocatePrefetchInstr=0
1488 -XX:AllocatePrefetchLines=lines
1490 Sets the number of cache lines to load after the last object al‐
1491 location by using the prefetch instructions generated in com‐
1492 piled code. The default value is 1 if the last allocated object
1493 was an instance, and 3 if it was an array.
1494 The following example shows how to set the number of loaded
1496 cache lines to 5:
1497 -XX:AllocatePrefetchLines=5
1499 -XX:AllocatePrefetchStepSize=size
1501 Sets the step size (in bytes) for sequential prefetch instruc‐
1502 tions. Append the letter k or K to indicate kilobytes, m or M
1503 to indicate megabytes, g or G to indicate gigabytes. By de‐
1504 fault, the step size is set to 16 bytes:
1505 -XX:AllocatePrefetchStepSize=16
1507 -XX:AllocatePrefetchStyle=style
1509 Sets the generated code style for prefetch instructions. The
1510 style argument is an integer from 0 to 3:
1511 0 Don't generate prefetch instructions.
1513 1 Execute prefetch instructions after each allocation.
1515 This is the default setting.
1516 2 Use the thread-local allocation block (TLAB) watermark
1518 pointer to determine when prefetch instructions are exe‐
1519 cuted.
1520 3 Generate one prefetch instruction per cache line.
1522 -XX:+BackgroundCompilation
1524 Enables background compilation. This option is enabled by de‐
1525 fault. To disable background compilation, specify -XX:-Back‐
1526 groundCompilation (this is equivalent to specifying -Xbatch).
1527 -XX:CICompilerCount=threads
1529 Sets the number of compiler threads to use for compilation. By
1530 default, the number of compiler threads is selected automatical‐
1531 ly depending on the number of CPUs and memory available for com‐
1532 piled code. The following example shows how to set the number
1533 of threads to 2:
1534 -XX:CICompilerCount=2
1536 -XX:+UseDynamicNumberOfCompilerThreads
1538 Dynamically create compiler thread up to the limit specified by
1539 -XX:CICompilerCount. This option is enabled by default.
1540 -XX:CompileCommand=command,method[,option]
1542 Specifies a command to perform on a method. For example, to ex‐
1543 clude the indexOf() method of the String class from being com‐
1544 piled, use the following:
1545 -XX:CompileCommand=exclude,java/lang/String.indexOf
1547 Note that the full class name is specified, including all pack‐
1549 ages and subpackages separated by a slash (/). For easier
1550 cut-and-paste operations, it's also possible to use the method
1551 name format produced by the -XX:+PrintCompilation and -XX:+Log‐
1552 Compilation options:
1553 -XX:CompileCommand=exclude,java.lang.String::indexOf
1555 If the method is specified without the signature, then the com‐
1557 mand is applied to all methods with the specified name. Howev‐
1558 er, you can also specify the signature of the method in the
1559 class file format. In this case, you should enclose the argu‐
1560 ments in quotation marks, because otherwise the shell treats the
1561 semicolon as a command end. For example, if you want to exclude
1562 only the indexOf(String) method of the String class from being
1563 compiled, use the following:
1564 -XX:CompileCommand="exclude,java/lang/String.index‐
1566 Of,(Ljava/lang/String;)I"
1567 You can also use the asterisk (*) as a wildcard for class and
1569 method names. For example, to exclude all indexOf() methods in
1570 all classes from being compiled, use the following:
1571 -XX:CompileCommand=exclude,*.indexOf
1573 The commas and periods are aliases for spaces, making it easier
1575 to pass compiler commands through a shell. You can pass argu‐
1576 ments to -XX:CompileCommand using spaces as separators by en‐
1577 closing the argument in quotation marks:
1578 -XX:CompileCommand="exclude java/lang/String indexOf"
1580 Note that after parsing the commands passed on the command line
1582 using the -XX:CompileCommand options, the JIT compiler then
1583 reads commands from the .hotspot_compiler file. You can add
1584 commands to this file or specify a different file using the
1585 -XX:CompileCommandFile option.
1586 To add several commands, either specify the -XX:CompileCommand
1588 option multiple times, or separate each argument with the new
1589 line separator (\n). The following commands are available:
1590 break Sets a breakpoint when debugging the JVM to stop at the
1592 beginning of compilation of the specified method.
1593 compileonly
1595 Excludes all methods from compilation except for the
1596 specified method. As an alternative, you can use the
1597 -XX:CompileOnly option, which lets you specify several
1598 methods.
1599 dontinline
1601 Prevents inlining of the specified method.
1602 exclude
1604 Excludes the specified method from compilation.
1605 help Prints a help message for the -XX:CompileCommand option.
1607 inline Attempts to inline the specified method.
1609 log Excludes compilation logging (with the -XX:+LogCompila‐
1611 tion option) for all methods except for the specified
1612 method. By default, logging is performed for all com‐
1613 piled methods.
1614 option Passes a JIT compilation option to the specified method
1616 in place of the last argument (option). The compilation
1617 option is set at the end, after the method name. For ex‐
1618 ample, to enable the BlockLayoutByFrequency option for
1619 the append() method of the StringBuffer class, use the
1620 following:
1621 -XX:CompileCommand=option,java/lang/String‐
1623 Buffer.append,BlockLayoutByFrequency
1624 You can specify multiple compilation options, separated
1626 by commas or spaces.
1627 print Prints generated assembler code after compilation of the
1629 specified method.
1630 quiet Instructs not to print the compile commands. By default,
1632 the commands that you specify with the -XX:CompileCommand
1633 option are printed; for example, if you exclude from com‐
1634 pilation the indexOf() method of the String class, then
1635 the following is printed to standard output:
1636 CompilerOracle: exclude java/lang/String.indexOf
1638 You can suppress this by specifying the -XX:CompileCom‐
1640 mand=quiet option before other -XX:CompileCommand op‐
1641 tions.
1642 -XX:CompileCommandFile=filename
1644 Sets the file from which JIT compiler commands are read. By de‐
1645 fault, the .hotspot_compiler file is used to store commands per‐
1646 formed by the JIT compiler.
1647 Each line in the command file represents a command, a class
1649 name, and a method name for which the command is used. For ex‐
1650 ample, this line prints assembly code for the toString() method
1651 of the String class:
1652 print java/lang/String toString
1654 If you're using commands for the JIT compiler to perform on
1656 methods, then see the -XX:CompileCommand option.
1657 -XX:CompilerDirectivesFile=file
1659 Adds directives from a file to the directives stack when a pro‐
1660 gram starts. See Compiler Control [https://docs.ora‐
1661 cle.com/en/java/javase/12/vm/compiler-con‐
1662 trol1.html#GUID-94AD8194-786A-4F19-BFFF-278F8E237F3A].
1663 The -XX:CompilerDirectivesFile option has to be used together
1665 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1666 nostic JVM options.
1667 -XX:+CompilerDirectivesPrint
1669 Prints the directives stack when the program starts or when a
1670 new directive is added.
1671 The -XX:+CompilerDirectivesPrint option has to be used together
1673 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1674 nostic JVM options.
1675 -XX:CompileOnly=methods
1677 Sets the list of methods (separated by commas) to which compila‐
1678 tion should be restricted. Only the specified methods are com‐
1679 piled. Specify each method with the full class name (including
1680 the packages and subpackages). For example, to compile only the
1681 length() method of the String class and the size() method of the
1682 List class, use the following:
1683 -XX:CompileOnly=java/lang/String.length,ja‐
1685 va/util/List.size
1686 Note that the full class name is specified, including all pack‐
1688 ages and subpackages separated by a slash (/). For easier cut
1689 and paste operations, it's also possible to use the method name
1690 format produced by the -XX:+PrintCompilation and -XX:+LogCompi‐
1691 lation options:
1692 -XX:CompileOnly=java.lang.String::length,ja‐
1694 va.util.List::size
1695 Although wildcards aren't supported, you can specify only the
1697 class or package name to compile all methods in that class or
1698 package, as well as specify just the method to compile methods
1699 with this name in any class:
1700 -XX:CompileOnly=java/lang/String
1702 -XX:CompileOnly=java/lang
1703 -XX:CompileOnly=.length
1704 -XX:CompileThresholdScaling=scale
1706 Provides unified control of first compilation. This option con‐
1707 trols when methods are first compiled for both the tiered and
1708 the nontiered modes of operation. The CompileThresholdScaling
1709 option has a floating point value between 0 and +Inf and scales
1710 the thresholds corresponding to the current mode of operation
1711 (both tiered and nontiered). Setting CompileThresholdScaling to
1712 a value less than 1.0 results in earlier compilation while val‐
1713 ues greater than 1.0 delay compilation. Setting CompileThresh‐
1714 oldScaling to 0 is equivalent to disabling compilation.
1715 -XX:+DoEscapeAnalysis
1717 Enables the use of escape analysis. This option is enabled by
1718 default. To disable the use of escape analysis, specify
1719 -XX:-DoEscapeAnalysis.
1720 -XX:InitialCodeCacheSize=size
1722 Sets the initial code cache size (in bytes). Append the letter
1723 k or K to indicate kilobytes, m or M to indicate megabytes, or g
1724 or G to indicate gigabytes. The default value depends on the
1725 platform. The initial code cache size shouldn't be less than
1726 the system's minimal memory page size. The following example
1727 shows how to set the initial code cache size to 32 KB:
1728 -XX:InitialCodeCacheSize=32k
1730 -XX:+Inline
1732 Enables method inlining. This option is enabled by default to
1733 increase performance. To disable method inlining, specify
1734 -XX:-Inline.
1735 -XX:InlineSmallCode=size
1737 Sets the maximum code size (in bytes) for already compiled meth‐
1738 ods that may be inlined. This flag only applies to the C2 com‐
1739 piler. Append the letter k or K to indicate kilobytes, m or M
1740 to indicate megabytes, or g or G to indicate gigabytes. The de‐
1741 fault value depends on the platform and on whether tiered compi‐
1742 lation is enabled. In the following example it is set to 1000
1743 bytes:
1744 -XX:InlineSmallCode=1000
1746 -XX:+LogCompilation
1748 Enables logging of compilation activity to a file named
1749 hotspot.log in the current working directory. You can specify a
1750 different log file path and name using the -XX:LogFile option.
1751 By default, this option is disabled and compilation activity
1753 isn't logged. The -XX:+LogCompilation option has to be used to‐
1754 gether with the -XX:UnlockDiagnosticVMOptions option that un‐
1755 locks diagnostic JVM options.
1756 You can enable verbose diagnostic output with a message printed
1758 to the console every time a method is compiled by using the
1759 -XX:+PrintCompilation option.
1760 -XX:FreqInlineSize=size
1762 Sets the maximum bytecode size (in bytes) of a hot method to be
1763 inlined. This flag only applies to the C2 compiler. Append the
1764 letter k or K to indicate kilobytes, m or M to indicate
1765 megabytes, or g or G to indicate gigabytes. The default value
1766 depends on the platform. In the following example it is set to
1767 325 bytes:
1768 -XX:FreqInlineSize=325
1770 -XX:MaxInlineSize=size
1772 Sets the maximum bytecode size (in bytes) of a cold method to be
1773 inlined. This flag only applies to the C2 compiler. Append the
1774 letter k or K to indicate kilobytes, m or M to indicate
1775 megabytes, or g or G to indicate gigabytes. By default, the
1776 maximum bytecode size is set to 35 bytes:
1777 -XX:MaxInlineSize=35
1779 -XX:C1MaxInlineSize=size
1781 Sets the maximum bytecode size (in bytes) of a cold method to be
1782 inlined. This flag only applies to the C1 compiler. Append the
1783 letter k or K to indicate kilobytes, m or M to indicate
1784 megabytes, or g or G to indicate gigabytes. By default, the
1785 maximum bytecode size is set to 35 bytes:
1786 -XX:MaxInlineSize=35
1788 -XX:MaxTrivialSize=size
1790 Sets the maximum bytecode size (in bytes) of a trivial method to
1791 be inlined. This flag only applies to the C2 compiler. Append
1792 the letter k or K to indicate kilobytes, m or M to indicate
1793 megabytes, or g or G to indicate gigabytes. By default, the
1794 maximum bytecode size of a trivial method is set to 6 bytes:
1795 -XX:MaxTrivialSize=6
1797 -XX:C1MaxTrivialSize=size
1799 Sets the maximum bytecode size (in bytes) of a trivial method to
1800 be inlined. This flag only applies to the C1 compiler. Append
1801 the letter k or K to indicate kilobytes, m or M to indicate
1802 megabytes, or g or G to indicate gigabytes. By default, the
1803 maximum bytecode size of a trivial method is set to 6 bytes:
1804 -XX:MaxTrivialSize=6
1806 -XX:MaxNodeLimit=nodes
1808 Sets the maximum number of nodes to be used during single method
1809 compilation. By default the value depends on the features en‐
1810 abled. In the following example the maximum number of nodes is
1811 set to 100,000:
1812 -XX:MaxNodeLimit=100000
1814 -XX:NonNMethodCodeHeapSize=size
1816 Sets the size in bytes of the code segment containing nonmethod
1817 code.
1818 A nonmethod code segment containing nonmethod code, such as com‐
1820 piler buffers and the bytecode interpreter. This code type
1821 stays in the code cache forever. This flag is used only if
1822 -XX:SegmentedCodeCache is enabled.
1823 -XX:NonProfiledCodeHeapSize=size
1825 Sets the size in bytes of the code segment containing nonpro‐
1826 filed methods. This flag is used only if -XX:SegmentedCodeCache
1827 is enabled.
1828 -XX:+OptimizeStringConcat
1830 Enables the optimization of String concatenation operations.
1831 This option is enabled by default. To disable the optimization
1832 of String concatenation operations, specify -XX:-OptimizeString‐
1833 Concat.
1834 -XX:+PrintAssembly
1836 Enables printing of assembly code for bytecoded and native meth‐
1837 ods by using the external hsdis-<arch>.so or .dll library. For
1838 64-bit VM on Windows, it's hsdis-amd64.dll. This lets you to
1839 see the generated code, which may help you to diagnose perfor‐
1840 mance issues.
1841 By default, this option is disabled and assembly code isn't
1843 printed. The -XX:+PrintAssembly option has to be used together
1844 with the -XX:UnlockDiagnosticVMOptions option that unlocks diag‐
1845 nostic JVM options.
1846 -XX:ProfiledCodeHeapSize=size
1848 Sets the size in bytes of the code segment containing profiled
1849 methods. This flag is used only if -XX:SegmentedCodeCache is
1850 enabled.
1851 -XX:+PrintCompilation
1853 Enables verbose diagnostic output from the JVM by printing a
1854 message to the console every time a method is compiled. This
1855 lets you to see which methods actually get compiled. By de‐
1856 fault, this option is disabled and diagnostic output isn't
1857 printed.
1858 You can also log compilation activity to a file by using the
1860 -XX:+LogCompilation option.
1861 -XX:+PrintInlining
1863 Enables printing of inlining decisions. This let's you see
1864 which methods are getting inlined.
1865 By default, this option is disabled and inlining information
1867 isn't printed. The -XX:+PrintInlining option has to be used to‐
1868 gether with the -XX:+UnlockDiagnosticVMOptions option that un‐
1869 locks diagnostic JVM options.
1870 -XX:ReservedCodeCacheSize=size
1872 Sets the maximum code cache size (in bytes) for JIT-compiled
1873 code. Append the letter k or K to indicate kilobytes, m or M to
1874 indicate megabytes, or g or G to indicate gigabytes. The de‐
1875 fault maximum code cache size is 240 MB; if you disable tiered
1876 compilation with the option -XX:-TieredCompilation, then the de‐
1877 fault size is 48 MB. This option has a limit of 2 GB; other‐
1878 wise, an error is generated. The maximum code cache size
1879 shouldn't be less than the initial code cache size; see the op‐
1880 tion -XX:InitialCodeCacheSize.
1881 -XX:RTMAbortRatio=abort_ratio
1883 Specifies the RTM abort ratio is specified as a percentage (%)
1884 of all executed RTM transactions. If a number of aborted trans‐
1885 actions becomes greater than this ratio, then the compiled code
1886 is deoptimized. This ratio is used when the -XX:+UseRTMDeopt
1887 option is enabled. The default value of this option is 50.
1888 This means that the compiled code is deoptimized if 50% of all
1889 transactions are aborted.
1890 -XX:RTMRetryCount=number_of_retries
1892 Specifies the number of times that the RTM locking code is re‐
1893 tried, when it is aborted or busy, before falling back to the
1894 normal locking mechanism. The default value for this option is
1895 5. The -XX:UseRTMLocking option must be enabled.
1896 -XX:+SegmentedCodeCache
1898 Enables segmentation of the code cache. Without the -XX:+Seg‐
1899 mentedCodeCache, the code cache consists of one large segment.
1900 With -XX:+SegmentedCodeCache, we have separate segments for non‐
1901 method, profiled method, and nonprofiled method code. These
1902 segments aren't resized at runtime. The feature is enabled by
1903 default if tiered compilation is enabled (-XX:+TieredCompilation
1904 ) and -XX:ReservedCodeCacheSize >= 240 MB. The advantages are
1905 better control of the memory footprint, reduced code fragmenta‐
1906 tion, and better iTLB/iCache behavior due to improved locality.
1907 iTLB/iCache is a CPU-specific term meaning Instruction Transla‐
1908 tion Lookaside Buffer (ITLB). ICache is an instruction cache in
1909 theCPU. The implementation of the code cache can be found in
1910 the file: /share/vm/code/codeCache.cpp.
1911 -XX:StartAggressiveSweepingAt=percent
1913 Forces stack scanning of active methods to aggressively remove
1914 unused code when only the given percentage of the code cache is
1915 free. The default value is 10%.
1916 -XX:-TieredCompilation
1918 Disables the use of tiered compilation. By default, this option
1919 is enabled.
1920 -XX:UseSSE=version
1922 Enables the use of SSE instruction set of a specified version.
1923 Is set by default to the highest supported version available
1924 (x86 only).
1925 -XX:UseAVX=version
1927 Enables the use of AVX instruction set of a specified version.
1928 Is set by default to the highest supported version available
1929 (x86 only).
1930 -XX:+UseAES
1932 Enables hardware-based AES intrinsics for hardware that supports
1933 it. This option is on by default on hardware that has the nec‐
1934 essary instructions. The -XX:+UseAES is used in conjunction
1935 with UseAESIntrinsics. Flags that control intrinsics now re‐
1936 quire the option -XX:+UnlockDiagnosticVMOptions.
1937 -XX:+UseAESIntrinsics
1939 Enables AES intrinsics. Specifying-XX:+UseAESIntrinsics is
1940 equivalent to also enabling -XX:+UseAES. To disable hard‐
1941 ware-based AES intrinsics, specify -XX:-UseAES -XX:-UseAESIn‐
1942 trinsics. For example, to enable hardware AES, use the follow‐
1943 ing flags:
1944 -XX:+UseAES -XX:+UseAESIntrinsics
1946 Flags that control intrinsics now require the option -XX:+Un‐
1948 lockDiagnosticVMOptions.
1949 -XX:+UseAESCTRIntrinsics
1951 Analogous to -XX:+UseAESIntrinsics enables AES/CTR intrinsics.
1952 -XX:+UseGHASHIntrinsics
1954 Controls the use of GHASH intrinsics. Enabled by default on
1955 platforms that support the corresponding instructions. Flags
1956 that control intrinsics now require the option -XX:+UnlockDiag‐
1957 nosticVMOptions.
1958 -XX:+UseBASE64Intrinsics
1960 Controls the use of accelerated BASE64 encoding routines for ja‐
1961 va.util.Base64. Enabled by default on platforms that support
1962 it. Flags that control intrinsics now require the option
1963 -XX:+UnlockDiagnosticVMOptions.
1964 -XX:+UseAdler32Intrinsics
1966 Controls the use of Adler32 checksum algorithm intrinsic for ja‐
1967 va.util.zip.Adler32. Enabled by default on platforms that sup‐
1968 port it. Flags that control intrinsics now require the option
1969 -XX:+UnlockDiagnosticVMOptions.
1970 -XX:+UseCRC32Intrinsics
1972 Controls the use of CRC32 intrinsics for java.util.zip.CRC32.
1973 Enabled by default on platforms that support it. Flags that
1974 control intrinsics now require the option -XX:+UnlockDiagnos‐
1975 ticVMOptions.
1976 -XX:+UseCRC32CIntrinsics
1978 Controls the use of CRC32C intrinsics for java.util.zip.CRC32C.
1979 Enabled by default on platforms that support it. Flags that
1980 control intrinsics now require the option -XX:+UnlockDiagnos‐
1981 ticVMOptions.
1982 -XX:+UseSHA
1984 Enables hardware-based intrinsics for SHA crypto hash functions
1985 for some hardware. The UseSHA option is used in conjunction
1986 with the UseSHA1Intrinsics, UseSHA256Intrinsics, and Use‐
1987 SHA512Intrinsics options.
1988 The UseSHA and UseSHA*Intrinsics flags are enabled by default on
1990 machines that support the corresponding instructions.
1991 This feature is applicable only when using the sun.securi‐
1993 ty.provider.Sun provider for SHA operations. Flags that control
1994 intrinsics now require the option -XX:+UnlockDiagnosticVMOp‐
1995 tions.
1996 To disable all hardware-based SHA intrinsics, specify the
1998 -XX:-UseSHA. To disable only a particular SHA intrinsic, use
1999 the appropriate corresponding option. For example: -XX:-Use‐
2000 SHA256Intrinsics.
2001 -XX:+UseSHA1Intrinsics
2003 Enables intrinsics for SHA-1 crypto hash function. Flags that
2004 control intrinsics now require the option -XX:+UnlockDiagnos‐
2005 ticVMOptions.
2006 -XX:+UseSHA256Intrinsics
2008 Enables intrinsics for SHA-224 and SHA-256 crypto hash func‐
2009 tions. Flags that control intrinsics now require the option
2010 -XX:+UnlockDiagnosticVMOptions.
2011 -XX:+UseSHA512Intrinsics
2013 Enables intrinsics for SHA-384 and SHA-512 crypto hash func‐
2014 tions. Flags that control intrinsics now require the option
2015 -XX:+UnlockDiagnosticVMOptions.
2016 -XX:+UseMathExactIntrinsics
2018 Enables intrinsification of various java.lang.Math.*Exact()
2019 functions. Enabled by default. Flags that control intrinsics
2020 now require the option -XX:+UnlockDiagnosticVMOptions.
2021 -XX:+UseMultiplyToLenIntrinsic
2023 Enables intrinsification of BigInteger.multiplyToLen(). Enabled
2024 by default on platforms that support it. Flags that control in‐
2025 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2026 -XX:+UseSquareToLenIntrinsic
2028 Enables intrinsification of BigInteger.squareToLen(). Enabled
2029 by default on platforms that support it. Flags that control in‐
2030 trinsics now require the option -XX:+UnlockDiagnosticVMOptions.
2031 -XX:+UseMulAddIntrinsic
2033 Enables intrinsification of BigInteger.mulAdd(). Enabled by de‐
2034 fault on platforms that support it. Flags that control intrin‐
2035 sics now require the option -XX:+UnlockDiagnosticVMOptions.
2036 -XX:+UseMontgomeryMultiplyIntrinsic
2038 Enables intrinsification of BigInteger.montgomeryMultiply().
2039 Enabled by default on platforms that support it. Flags that
2040 control intrinsics now require the option -XX:+UnlockDiagnos‐
2041 ticVMOptions.
2042 -XX:+UseMontgomerySquareIntrinsic
2044 Enables intrinsification of BigInteger.montgomerySquare(). En‐
2045 abled by default on platforms that support it. Flags that con‐
2046 trol intrinsics now require the option -XX:+UnlockDiagnosticV‐
2047 MOptions.
2048 -XX:+UseCMoveUnconditionally
2050 Generates CMove (scalar and vector) instructions regardless of
2051 profitability analysis.
2052 -XX:+UseCodeCacheFlushing
2054 Enables flushing of the code cache before shutting down the com‐
2055 piler. This option is enabled by default. To disable flushing
2056 of the code cache before shutting down the compiler, specify
2057 -XX:-UseCodeCacheFlushing.
2058 -XX:+UseCondCardMark
2060 Enables checking if the card is already marked before updating
2061 the card table. This option is disabled by default. It should
2062 be used only on machines with multiple sockets, where it in‐
2063 creases the performance of Java applications that rely on con‐
2064 current operations.
2065 -XX:+UseCountedLoopSafepoints
2067 Keeps safepoints in counted loops. Its default value depends on
2068 whether the selected garbage collector requires low latency
2069 safepoints.
2070 -XX:LoopStripMiningIter=number_of_iterations
2072 Controls the number of iterations in the inner strip mined loop.
2073 Strip mining transforms counted loops into two level nested
2074 loops. Safepoints are kept in the outer loop while the inner
2075 loop can execute at full speed. This option controls the maxi‐
2076 mum number of iterations in the inner loop. The default value
2077 is 1,000.
2078 -XX:LoopStripMiningIterShortLoop=number_of_iterations
2080 Controls loop strip mining optimization. Loops with the number
2081 of iterations less than specified will not have safepoints in
2082 them. Default value is 1/10th of -XX:LoopStripMiningIter.
2083 -XX:+UseFMA
2085 Enables hardware-based FMA intrinsics for hardware where FMA in‐
2086 structions are available (such as, Intel and ARM64). FMA in‐
2087 trinsics are generated for the java.lang.Math.fma(a, b, c) meth‐
2088 ods that calculate the value of ( a * b + c ) expressions.
2089 -XX:+UseRTMDeopt
2091 Autotunes RTM locking depending on the abort ratio. This ratio
2092 is specified by the -XX:RTMAbortRatio option. If the number of
2093 aborted transactions exceeds the abort ratio, then the method
2094 containing the lock is deoptimized and recompiled with all locks
2095 as normal locks. This option is disabled by default. The
2096 -XX:+UseRTMLocking option must be enabled.
2097 -XX:+UseRTMLocking
2099 Generates Restricted Transactional Memory (RTM) locking code for
2100 all inflated locks, with the normal locking mechanism as the
2101 fallback handler. This option is disabled by default. Options
2102 related to RTM are available only on x86 CPUs that support
2103 Transactional Synchronization Extensions (TSX).
2104 RTM is part of Intel's TSX, which is an x86 instruction set ex‐
2106 tension and facilitates the creation of multithreaded applica‐
2107 tions. RTM introduces the new instructions XBEGIN, XABORT,
2108 XEND, and XTEST. The XBEGIN and XEND instructions enclose a set
2109 of instructions to run as a transaction. If no conflict is
2110 found when running the transaction, then the memory and register
2111 modifications are committed together at the XEND instruction.
2112 The XABORT instruction can be used to explicitly abort a trans‐
2113 action and the XTEST instruction checks if a set of instructions
2114 is being run in a transaction.
2115 A lock on a transaction is inflated when another thread tries to
2117 access the same transaction, thereby blocking the thread that
2118 didn't originally request access to the transaction. RTM re‐
2119 quires that a fallback set of operations be specified in case a
2120 transaction aborts or fails. An RTM lock is a lock that has
2121 been delegated to the TSX's system.
2122 RTM improves performance for highly contended locks with low
2124 conflict in a critical region (which is code that must not be
2125 accessed by more than one thread concurrently). RTM also im‐
2126 proves the performance of coarse-grain locking, which typically
2127 doesn't perform well in multithreaded applications.
2128 (Coarse-grain locking is the strategy of holding locks for long
2129 periods to minimize the overhead of taking and releasing locks,
2130 while fine-grained locking is the strategy of trying to achieve
2131 maximum parallelism by locking only when necessary and unlocking
2132 as soon as possible.) Also, for lightly contended locks that are
2133 used by different threads, RTM can reduce false cache line shar‐
2134 ing, also known as cache line ping-pong. This occurs when mul‐
2135 tiple threads from different processors are accessing different
2136 resources, but the resources share the same cache line. As a
2137 result, the processors repeatedly invalidate the cache lines of
2138 other processors, which forces them to read from main memory in‐
2139 stead of their cache.
2140 -XX:+UseSuperWord
2142 Enables the transformation of scalar operations into superword
2143 operations. Superword is a vectorization optimization. This
2144 option is enabled by default. To disable the transformation of
2145 scalar operations into superword operations, specify -XX:-UseSu‐
2146 perWord.
2147
2149 These java options provide the ability to gather system information and
2150 perform extensive debugging.
2151 -XX:+DisableAttachMechanism
2153 Disables the mechanism that lets tools attach to the JVM. By
2154 default, this option is disabled, meaning that the attach mecha‐
2155 nism is enabled and you can use diagnostics and troubleshooting
2156 tools such as jcmd, jstack, jmap, and jinfo.
2157 Note: The tools such as jcmd, jinfo, jmap, and jstack
2159 shipped with the JDK aren't supported when using the
2160 tools from one JDK version to troubleshoot a different
2161 JDK version.
2162 -XX:+ExtendedDTraceProbes
2164 Linux and macOS: Enables additional dtrace tool probes that af‐
2165 fect the performance. By default, this option is disabled and
2166 dtrace performs only standard probes.
2167 -XX:+HeapDumpOnOutOfMemoryError
2169 Enables the dumping of the Java heap to a file in the current
2170 directory by using the heap profiler (HPROF) when a ja‐
2171 va.lang.OutOfMemoryError exception is thrown. You can explicit‐
2172 ly set the heap dump file path and name using the -XX:HeapDump‐
2173 Path option. By default, this option is disabled and the heap
2174 isn't dumped when an OutOfMemoryError exception is thrown.
2175 -XX:HeapDumpPath=path
2177 Sets the path and file name for writing the heap dump provided
2178 by the heap profiler (HPROF) when the -XX:+HeapDumpOnOutOfMemo‐
2179 ryError option is set. By default, the file is created in the
2180 current working directory, and it's named java_pid<pid>.hprof
2181 where <pid> is the identifier of the process that caused the er‐
2182 ror. The following example shows how to set the default file
2183 explicitly (%p represents the current process identifier):
2184 -XX:HeapDumpPath=./java_pid%p.hprof
2186 • Linux and macOS: The following example shows how to set the
2188 heap dump file to /var/log/java/java_heapdump.hprof:
2189 -XX:HeapDumpPath=/var/log/java/java_heapdump.hprof
2191 • Windows: The following example shows how to set the heap dump
2193 file to C:/log/java/java_heapdump.log:
2194 -XX:HeapDumpPath=C:/log/java/java_heapdump.log
2196 -XX:LogFile=path
2198 Sets the path and file name to where log data is written. By
2199 default, the file is created in the current working directory,
2200 and it's named hotspot.log.
2201 • Linux and macOS: The following example shows how to set the
2203 log file to /var/log/java/hotspot.log:
2204 -XX:LogFile=/var/log/java/hotspot.log
2206 • Windows: The following example shows how to set the log file
2208 to C:/log/java/hotspot.log:
2209 -XX:LogFile=C:/log/java/hotspot.log
2211 -XX:+PrintClassHistogram
2213 Enables printing of a class instance histogram after one of the
2214 following events:
2215 • Linux and macOS: Control+Break
2217 • Windows: Control+C (SIGTERM)
2219 By default, this option is disabled.
2221 Setting this option is equivalent to running the jmap -histo
2223 command, or the jcmd pid GC.class_histogram command, where pid
2224 is the current Java process identifier.
2225 -XX:+PrintConcurrentLocks
2227 Enables printing of java.util.concurrent locks after one of the
2228 following events:
2229 • Linux and macOS: Control+Break
2231 • Windows: Control+C (SIGTERM)
2233 By default, this option is disabled.
2235 Setting this option is equivalent to running the jstack -l com‐
2237 mand or the jcmd pid Thread.print -l command, where pid is the
2238 current Java process identifier.
2239 -XX:+PrintFlagsRanges
2241 Prints the range specified and allows automatic testing of the
2242 values. See Validate Java Virtual Machine Flag Arguments.
2243 -XX:+PerfDataSaveToFile
2245 If enabled, saves jstat binary data when the Java application
2246 exits. This binary data is saved in a file named hsperfda‐
2247 ta_pid, where pid is the process identifier of the Java applica‐
2248 tion that you ran. Use the jstat command to display the perfor‐
2249 mance data contained in this file as follows:
2250 jstat -class file:///path/hsperfdata_pid
2252 jstat -gc file:///path/hsperfdata_pid
2254 -XX:+UsePerfData
2256 Enables the perfdata feature. This option is enabled by default
2257 to allow JVM monitoring and performance testing. Disabling it
2258 suppresses the creation of the hsperfdata_userid directories.
2259 To disable the perfdata feature, specify -XX:-UsePerfData.
2260
2262 These java options control how garbage collection (GC) is performed by
2263 the Java HotSpot VM.
2264 -XX:+AggressiveHeap
2266 Enables Java heap optimization. This sets various parameters to
2267 be optimal for long-running jobs with intensive memory alloca‐
2268 tion, based on the configuration of the computer (RAM and CPU).
2269 By default, the option is disabled and the heap sizes are con‐
2270 figured less aggressively.
2271 -XX:+AlwaysPreTouch
2273 Requests the VM to touch every page on the Java heap after re‐
2274 questing it from the operating system and before handing memory
2275 out to the application. By default, this option is disabled and
2276 all pages are committed as the application uses the heap space.
2277 -XX:ConcGCThreads=threads
2279 Sets the number of threads used for concurrent GC. Sets threads
2280 to approximately 1/4 of the number of parallel garbage collec‐
2281 tion threads. The default value depends on the number of CPUs
2282 available to the JVM.
2283 For example, to set the number of threads for concurrent GC to
2285 2, specify the following option:
2286 -XX:ConcGCThreads=2
2288 -XX:+DisableExplicitGC
2290 Enables the option that disables processing of calls to the Sys‐
2291 tem.gc() method. This option is disabled by default, meaning
2292 that calls to System.gc() are processed. If processing of calls
2293 to System.gc() is disabled, then the JVM still performs GC when
2294 necessary.
2295 -XX:+ExplicitGCInvokesConcurrent
2297 Enables invoking of concurrent GC by using the System.gc() re‐
2298 quest. This option is disabled by default and can be enabled
2299 only with the -XX:+UseG1GC option.
2300 -XX:G1AdaptiveIHOPNumInitialSamples=number
2302 When -XX:UseAdaptiveIHOP is enabled, this option sets the number
2303 of completed marking cycles used to gather samples until G1
2304 adaptively determines the optimum value of -XX:InitiatingHeapOc‐
2305 cupancyPercent. Before, G1 uses the value of -XX:Initiat‐
2306 ingHeapOccupancyPercent directly for this purpose. The default
2307 value is 3.
2308 -XX:G1HeapRegionSize=size
2310 Sets the size of the regions into which the Java heap is subdi‐
2311 vided when using the garbage-first (G1) collector. The value is
2312 a power of 2 and can range from 1 MB to 32 MB. The default re‐
2313 gion size is determined ergonomically based on the heap size
2314 with a goal of approximately 2048 regions.
2315 The following example sets the size of the subdivisions to 16
2317 MB:
2318 -XX:G1HeapRegionSize=16m
2320 -XX:G1HeapWastePercent=percent
2322 Sets the percentage of heap that you're willing to waste. The
2323 Java HotSpot VM doesn't initiate the mixed garbage collection
2324 cycle when the reclaimable percentage is less than the heap
2325 waste percentage. The default is 5 percent.
2326 -XX:G1MaxNewSizePercent=percent
2328 Sets the percentage of the heap size to use as the maximum for
2329 the young generation size. The default value is 60 percent of
2330 your Java heap.
2331 This is an experimental flag. This setting replaces the -XX:De‐
2333 faultMaxNewGenPercent setting.
2334 -XX:G1MixedGCCountTarget=number
2336 Sets the target number of mixed garbage collections after a
2337 marking cycle to collect old regions with at most G1MixedG‐
2338 CLIveThresholdPercent live data. The default is 8 mixed garbage
2339 collections. The goal for mixed collections is to be within
2340 this target number.
2341 -XX:G1MixedGCLiveThresholdPercent=percent
2343 Sets the occupancy threshold for an old region to be included in
2344 a mixed garbage collection cycle. The default occupancy is 85
2345 percent.
2346 This is an experimental flag. This setting replaces the
2348 -XX:G1OldCSetRegionLiveThresholdPercent setting.
2349 -XX:G1NewSizePercent=percent
2351 Sets the percentage of the heap to use as the minimum for the
2352 young generation size. The default value is 5 percent of your
2353 Java heap.
2354 This is an experimental flag. This setting replaces the -XX:De‐
2356 faultMinNewGenPercent setting.
2357 -XX:G1OldCSetRegionThresholdPercent=percent
2359 Sets an upper limit on the number of old regions to be collected
2360 during a mixed garbage collection cycle. The default is 10 per‐
2361 cent of the Java heap.
2362 -XX:G1ReservePercent=percent
2364 Sets the percentage of the heap (0 to 50) that's reserved as a
2365 false ceiling to reduce the possibility of promotion failure for
2366 the G1 collector. When you increase or decrease the percentage,
2367 ensure that you adjust the total Java heap by the same amount.
2368 By default, this option is set to 10%.
2369 The following example sets the reserved heap to 20%:
2371 -XX:G1ReservePercent=20
2373 -XX:+G1UseAdaptiveIHOP
2375 Controls adaptive calculation of the old generation occupancy to
2376 start background work preparing for an old generation collec‐
2377 tion. If enabled, G1 uses -XX:InitiatingHeapOccupancyPercent
2378 for the first few times as specified by the value of -XX:G1Adap‐
2379 tiveIHOPNumInitialSamples, and after that adaptively calculates
2380 a new optimum value for the initiating occupancy automatically.
2381 Otherwise, the old generation collection process always starts
2382 at the old generation occupancy determined by -XX:Initiat‐
2383 ingHeapOccupancyPercent.
2384 The default is enabled.
2386 -XX:InitialHeapSize=size
2388 Sets the initial size (in bytes) of the memory allocation pool.
2389 This value must be either 0, or a multiple of 1024 and greater
2390 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2391 M to indicate megabytes, or g or G to indicate gigabytes. The
2392 default value is selected at run time based on the system con‐
2393 figuration.
2394 The following examples show how to set the size of allocated
2396 memory to 6 MB using various units:
2397 -XX:InitialHeapSize=6291456
2399 -XX:InitialHeapSize=6144k
2400 -XX:InitialHeapSize=6m
2401 If you set this option to 0, then the initial size is set as the
2403 sum of the sizes allocated for the old generation and the young
2404 generation. The size of the heap for the young generation can
2405 be set using the -XX:NewSize option.
2406 -XX:InitialRAMPercentage=percent
2408 Sets the initial amount of memory that the JVM will use for the
2409 Java heap before applying ergonomics heuristics as a percentage
2410 of the maximum amount determined as described in the -XX:MaxRAM
2411 option. The default value is 1.5625 percent.
2412 The following example shows how to set the percentage of the
2414 initial amount of memory used for the Java heap:
2415 -XX:InitialRAMPercentage=5
2417 -XX:InitialSurvivorRatio=ratio
2419 Sets the initial survivor space ratio used by the throughput
2420 garbage collector (which is enabled by the -XX:+UseParallelGC
2421 option). Adaptive sizing is enabled by default with the
2422 throughput garbage collector by using the -XX:+UseParallelGC op‐
2423 tion, and the survivor space is resized according to the appli‐
2424 cation behavior, starting with the initial value. If adaptive
2425 sizing is disabled (using the -XX:-UseAdaptiveSizePolicy op‐
2426 tion), then the -XX:SurvivorRatio option should be used to set
2427 the size of the survivor space for the entire execution of the
2428 application.
2429 The following formula can be used to calculate the initial size
2431 of survivor space (S) based on the size of the young generation
2432 (Y), and the initial survivor space ratio (R):
2433 S=Y/(R+2)
2435 The 2 in the equation denotes two survivor spaces. The larger
2437 the value specified as the initial survivor space ratio, the
2438 smaller the initial survivor space size.
2439 By default, the initial survivor space ratio is set to 8. If
2441 the default value for the young generation space size is used (2
2442 MB), then the initial size of the survivor space is 0.2 MB.
2443 The following example shows how to set the initial survivor
2445 space ratio to 4:
2446 -XX:InitialSurvivorRatio=4
2448 -XX:InitiatingHeapOccupancyPercent=percent
2450 Sets the percentage of the old generation occupancy (0 to 100)
2451 at which to start the first few concurrent marking cycles for
2452 the G1 garbage collector.
2453 By default, the initiating value is set to 45%. A value of 0
2455 implies nonstop concurrent GC cycles from the beginning until G1
2456 adaptively sets this value.
2457 See also the -XX:G1UseAdaptiveIHOP and -XX:G1AdaptiveIHOPNumIni‐
2459 tialSamples options.
2460 The following example shows how to set the initiating heap occu‐
2462 pancy to 75%:
2463 -XX:InitiatingHeapOccupancyPercent=75
2465 -XX:MaxGCPauseMillis=time
2467 Sets a target for the maximum GC pause time (in milliseconds).
2468 This is a soft goal, and the JVM will make its best effort to
2469 achieve it. The specified value doesn't adapt to your heap
2470 size. By default, for G1 the maximum pause time target is 200
2471 milliseconds. The other generational collectors do not use a
2472 pause time goal by default.
2473 The following example shows how to set the maximum target pause
2475 time to 500 ms:
2476 -XX:MaxGCPauseMillis=500
2478 -XX:MaxHeapSize=size
2480 Sets the maximum size (in byes) of the memory allocation pool.
2481 This value must be a multiple of 1024 and greater than 2 MB.
2482 Append the letter k or K to indicate kilobytes, m or M to indi‐
2483 cate megabytes, or g or G to indicate gigabytes. The default
2484 value is selected at run time based on the system configuration.
2485 For server deployments, the options -XX:InitialHeapSize and
2486 -XX:MaxHeapSize are often set to the same value.
2487 The following examples show how to set the maximum allowed size
2489 of allocated memory to 80 MB using various units:
2490 -XX:MaxHeapSize=83886080
2492 -XX:MaxHeapSize=81920k
2493 -XX:MaxHeapSize=80m
2494 The -XX:MaxHeapSize option is equivalent to -Xmx.
2496 -XX:MaxHeapFreeRatio=percent
2498 Sets the maximum allowed percentage of free heap space (0 to
2499 100) after a GC event. If free heap space expands above this
2500 value, then the heap is shrunk. By default, this value is set
2501 to 70%.
2502 Minimize the Java heap size by lowering the values of the param‐
2504 eters MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRa‐
2505 tio (default value is 40%) with the command-line options
2506 -XX:MaxHeapFreeRatio and -XX:MinHeapFreeRatio. Lowering Max‐
2507 HeapFreeRatio to as low as 10% and MinHeapFreeRatio to 5% has
2508 successfully reduced the heap size without too much performance
2509 regression; however, results may vary greatly depending on your
2510 application. Try different values for these parameters until
2511 they're as low as possible yet still retain acceptable perfor‐
2512 mance.
2513 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2515 Customers trying to keep the heap small should also add the op‐
2517 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2518 for a description of using this option to keep the Java heap
2519 small by reducing the dynamic footprint for embedded applica‐
2520 tions.
2521 -XX:MaxMetaspaceSize=size
2523 Sets the maximum amount of native memory that can be allocated
2524 for class metadata. By default, the size isn't limited. The
2525 amount of metadata for an application depends on the application
2526 itself, other running applications, and the amount of memory
2527 available on the system.
2528 The following example shows how to set the maximum class metada‐
2530 ta size to 256 MB:
2531 -XX:MaxMetaspaceSize=256m
2533 -XX:MaxNewSize=size
2535 Sets the maximum size (in bytes) of the heap for the young gen‐
2536 eration (nursery). The default value is set ergonomically.
2537 -XX:MaxRAM=size
2539 Sets the maximum amount of memory that the JVM may use for the
2540 Java heap before applying ergonomics heuristics. The default
2541 value is the maximum amount of available memory to the JVM
2542 process or 128 GB, whichever is lower.
2543 The maximum amount of available memory to the JVM process is the
2545 minimum of the machine's physical memory and any constraints set
2546 by the environment (e.g. container).
2547 Specifying this option disables automatic use of compressed oops
2549 if the combined result of this and other options influencing the
2550 maximum amount of memory is larger than the range of memory ad‐
2551 dressable by compressed oops. See -XX:UseCompressedOops for
2552 further information about compressed oops.
2553 The following example shows how to set the maximum amount of
2555 available memory for sizing the Java heap to 2 GB:
2556 -XX:MaxRAM=2G
2558 -XX:MaxRAMPercentage=percent
2560 Sets the maximum amount of memory that the JVM may use for the
2561 Java heap before applying ergonomics heuristics as a percentage
2562 of the maximum amount determined as described in the -XX:MaxRAM
2563 option. The default value is 25 percent.
2564 Specifying this option disables automatic use of compressed oops
2566 if the combined result of this and other options influencing the
2567 maximum amount of memory is larger than the range of memory ad‐
2568 dressable by compressed oops. See -XX:UseCompressedOops for
2569 further information about compressed oops.
2570 The following example shows how to set the percentage of the
2572 maximum amount of memory used for the Java heap:
2573 -XX:MaxRAMPercentage=75
2575 -XX:MinRAMPercentage=percent
2577 Sets the maximum amount of memory that the JVM may use for the
2578 Java heap before applying ergonomics heuristics as a percentage
2579 of the maximum amount determined as described in the -XX:MaxRAM
2580 option for small heaps. A small heap is a heap of approximately
2581 125 MB. The default value is 50 percent.
2582 The following example shows how to set the percentage of the
2584 maximum amount of memory used for the Java heap for small heaps:
2585 -XX:MinRAMPercentage=75
2587 -XX:MaxTenuringThreshold=threshold
2589 Sets the maximum tenuring threshold for use in adaptive GC siz‐
2590 ing. The largest value is 15. The default value is 15 for the
2591 parallel (throughput) collector.
2592 The following example shows how to set the maximum tenuring
2594 threshold to 10:
2595 -XX:MaxTenuringThreshold=10
2597 -XX:MetaspaceSize=size
2599 Sets the size of the allocated class metadata space that trig‐
2600 gers a garbage collection the first time it's exceeded. This
2601 threshold for a garbage collection is increased or decreased de‐
2602 pending on the amount of metadata used. The default size de‐
2603 pends on the platform.
2604 -XX:MinHeapFreeRatio=percent
2606 Sets the minimum allowed percentage of free heap space (0 to
2607 100) after a GC event. If free heap space falls below this val‐
2608 ue, then the heap is expanded. By default, this value is set to
2609 40%.
2610 Minimize Java heap size by lowering the values of the parameters
2612 MaxHeapFreeRatio (default value is 70%) and MinHeapFreeRatio
2613 (default value is 40%) with the command-line options -XX:Max‐
2614 HeapFreeRatio and -XX:MinHeapFreeRatio. Lowering MaxHeapFreeRa‐
2615 tio to as low as 10% and MinHeapFreeRatio to 5% has successfully
2616 reduced the heap size without too much performance regression;
2617 however, results may vary greatly depending on your application.
2618 Try different values for these parameters until they're as low
2619 as possible, yet still retain acceptable performance.
2620 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
2622 Customers trying to keep the heap small should also add the op‐
2624 tion -XX:-ShrinkHeapInSteps. See Performance Tuning Examples
2625 for a description of using this option to keep the Java heap
2626 small by reducing the dynamic footprint for embedded applica‐
2627 tions.
2628 -XX:MinHeapSize=size
2630 Sets the minimum size (in bytes) of the memory allocation pool.
2631 This value must be either 0, or a multiple of 1024 and greater
2632 than 1 MB. Append the letter k or K to indicate kilobytes, m or
2633 M to indicate megabytes, or g or G to indicate gigabytes. The
2634 default value is selected at run time based on the system con‐
2635 figuration.
2636 The following examples show how to set the mimimum size of allo‐
2638 cated memory to 6 MB using various units:
2639 -XX:MinHeapSize=6291456
2641 -XX:MinHeapSize=6144k
2642 -XX:MinHeapSize=6m
2643 If you set this option to 0, then the minimum size is set to the
2645 same value as the initial size.
2646 -XX:NewRatio=ratio
2648 Sets the ratio between young and old generation sizes. By de‐
2649 fault, this option is set to 2. The following example shows how
2650 to set the young-to-old ratio to 1:
2651 -XX:NewRatio=1
2653 -XX:NewSize=size
2655 Sets the initial size (in bytes) of the heap for the young gen‐
2656 eration (nursery). Append the letter k or K to indicate kilo‐
2657 bytes, m or M to indicate megabytes, or g or G to indicate giga‐
2658 bytes.
2659 The young generation region of the heap is used for new objects.
2661 GC is performed in this region more often than in other regions.
2662 If the size for the young generation is too low, then a large
2663 number of minor GCs are performed. If the size is too high,
2664 then only full GCs are performed, which can take a long time to
2665 complete. It is recommended that you keep the size for the
2666 young generation greater than 25% and less than 50% of the over‐
2667 all heap size.
2668 The following examples show how to set the initial size of the
2670 young generation to 256 MB using various units:
2671 -XX:NewSize=256m
2673 -XX:NewSize=262144k
2674 -XX:NewSize=268435456
2675 The -XX:NewSize option is equivalent to -Xmn.
2677 -XX:ParallelGCThreads=threads
2679 Sets the number of the stop-the-world (STW) worker threads. The
2680 default value depends on the number of CPUs available to the JVM
2681 and the garbage collector selected.
2682 For example, to set the number of threads for G1 GC to 2, speci‐
2684 fy the following option:
2685 -XX:ParallelGCThreads=2
2687 -XX:+ParallelRefProcEnabled
2689 Enables parallel reference processing. By default, this option
2690 is disabled.
2691 -XX:+PrintAdaptiveSizePolicy
2693 Enables printing of information about adaptive-generation siz‐
2694 ing. By default, this option is disabled.
2695 -XX:+ScavengeBeforeFullGC
2697 Enables GC of the young generation before each full GC. This
2698 option is enabled by default. It is recommended that you don't
2699 disable it, because scavenging the young generation before a
2700 full GC can reduce the number of objects reachable from the old
2701 generation space into the young generation space. To disable GC
2702 of the young generation before each full GC, specify the option
2703 -XX:-ScavengeBeforeFullGC.
2704 -XX:SoftRefLRUPolicyMSPerMB=time
2706 Sets the amount of time (in milliseconds) a softly reachable ob‐
2707 ject is kept active on the heap after the last time it was ref‐
2708 erenced. The default value is one second of lifetime per free
2709 megabyte in the heap. The -XX:SoftRefLRUPolicyMSPerMB option
2710 accepts integer values representing milliseconds per one
2711 megabyte of the current heap size (for Java HotSpot Client VM)
2712 or the maximum possible heap size (for Java HotSpot Server VM).
2713 This difference means that the Client VM tends to flush soft
2714 references rather than grow the heap, whereas the Server VM
2715 tends to grow the heap rather than flush soft references. In
2716 the latter case, the value of the -Xmx option has a significant
2717 effect on how quickly soft references are garbage collected.
2718 The following example shows how to set the value to 2.5 seconds:
2720 -XX:SoftRefLRUPolicyMSPerMB=2500
2722 -XX:-ShrinkHeapInSteps
2724 Incrementally reduces the Java heap to the target size, speci‐
2725 fied by the option -XX:MaxHeapFreeRatio. This option is enabled
2726 by default. If disabled, then it immediately reduces the Java
2727 heap to the target size instead of requiring multiple garbage
2728 collection cycles. Disable this option if you want to minimize
2729 the Java heap size. You will likely encounter performance
2730 degradation when this option is disabled.
2731 See Performance Tuning Examples for a description of using the
2733 MaxHeapFreeRatio option to keep the Java heap small by reducing
2734 the dynamic footprint for embedded applications.
2735 -XX:StringDeduplicationAgeThreshold=threshold
2737 Identifies String objects reaching the specified age that are
2738 considered candidates for deduplication. An object's age is a
2739 measure of how many times it has survived garbage collection.
2740 This is sometimes referred to as tenuring.
2741 Note: String objects that are promoted to an old heap re‐
2743 gion before this age has been reached are always consid‐
2744 ered candidates for deduplication. The default value for
2745 this option is 3. See the -XX:+UseStringDeduplication
2746 option.
2747 -XX:SurvivorRatio=ratio
2749 Sets the ratio between eden space size and survivor space size.
2750 By default, this option is set to 8. The following example
2751 shows how to set the eden/survivor space ratio to 4:
2752 -XX:SurvivorRatio=4
2754 -XX:TargetSurvivorRatio=percent
2756 Sets the desired percentage of survivor space (0 to 100) used
2757 after young garbage collection. By default, this option is set
2758 to 50%.
2759 The following example shows how to set the target survivor space
2761 ratio to 30%:
2762 -XX:TargetSurvivorRatio=30
2764 -XX:TLABSize=size
2766 Sets the initial size (in bytes) of a thread-local allocation
2767 buffer (TLAB). Append the letter k or K to indicate kilobytes,
2768 m or M to indicate megabytes, or g or G to indicate gigabytes.
2769 If this option is set to 0, then the JVM selects the initial
2770 size automatically.
2771 The following example shows how to set the initial TLAB size to
2773 512 KB:
2774 -XX:TLABSize=512k
2776 -XX:+UseAdaptiveSizePolicy
2778 Enables the use of adaptive generation sizing. This option is
2779 enabled by default. To disable adaptive generation sizing,
2780 specify -XX:-UseAdaptiveSizePolicy and set the size of the memo‐
2781 ry allocation pool explicitly. See the -XX:SurvivorRatio op‐
2782 tion.
2783 -XX:+UseG1GC
2785 Enables the use of the garbage-first (G1) garbage collector.
2786 It's a server-style garbage collector, targeted for multiproces‐
2787 sor machines with a large amount of RAM. This option meets GC
2788 pause time goals with high probability, while maintaining good
2789 throughput. The G1 collector is recommended for applications
2790 requiring large heaps (sizes of around 6 GB or larger) with lim‐
2791 ited GC latency requirements (a stable and predictable pause
2792 time below 0.5 seconds). By default, this option is enabled and
2793 G1 is used as the default garbage collector.
2794 -XX:+UseGCOverheadLimit
2796 Enables the use of a policy that limits the proportion of time
2797 spent by the JVM on GC before an OutOfMemoryError exception is
2798 thrown. This option is enabled, by default, and the parallel GC
2799 will throw an OutOfMemoryError if more than 98% of the total
2800 time is spent on garbage collection and less than 2% of the heap
2801 is recovered. When the heap is small, this feature can be used
2802 to prevent applications from running for long periods of time
2803 with little or no progress. To disable this option, specify the
2804 option -XX:-UseGCOverheadLimit.
2805 -XX:+UseNUMA
2807 Enables performance optimization of an application on a machine
2808 with nonuniform memory architecture (NUMA) by increasing the ap‐
2809 plication's use of lower latency memory. By default, this op‐
2810 tion is disabled and no optimization for NUMA is made. The op‐
2811 tion is available only when the parallel garbage collector is
2812 used (-XX:+UseParallelGC).
2813 -XX:+UseParallelGC
2815 Enables the use of the parallel scavenge garbage collector (also
2816 known as the throughput collector) to improve the performance of
2817 your application by leveraging multiple processors.
2818 By default, this option is disabled and the default collector is
2820 used.
2821 -XX:+UseSerialGC
2823 Enables the use of the serial garbage collector. This is gener‐
2824 ally the best choice for small and simple applications that
2825 don't require any special functionality from garbage collection.
2826 By default, this option is disabled and the default collector is
2827 used.
2828 -XX:+UseSHM
2830 Linux only: Enables the JVM to use shared memory to set up large
2831 pages.
2832 See Large Pages for setting up large pages.
2834 -XX:+UseStringDeduplication
2836 Enables string deduplication. By default, this option is dis‐
2837 abled. To use this option, you must enable the garbage-first
2838 (G1) garbage collector.
2839 String deduplication reduces the memory footprint of String ob‐
2841 jects on the Java heap by taking advantage of the fact that many
2842 String objects are identical. Instead of each String object
2843 pointing to its own character array, identical String objects
2844 can point to and share the same character array.
2845 -XX:+UseTLAB
2847 Enables the use of thread-local allocation blocks (TLABs) in the
2848 young generation space. This option is enabled by default. To
2849 disable the use of TLABs, specify the option -XX:-UseTLAB.
2850 -XX:+UseZGC
2852 Enables the use of the Z garbage collector (ZGC). This is a low
2853 latency garbage collector, providing max pause times of a few
2854 milliseconds, at some throughput cost. Pause times are indepen‐
2855 dent of what heap size is used. Supports heap sizes from 8MB to
2856 16TB.
2857 -XX:ZAllocationSpikeTolerance=factor
2859 Sets the allocation spike tolerance for ZGC. By default, this
2860 option is set to 2.0. This factor describes the level of allo‐
2861 cation spikes to expect. For example, using a factor of 3.0
2862 means the current allocation rate can be expected to triple at
2863 any time.
2864 -XX:ZCollectionInterval=seconds
2866 Sets the maximum interval (in seconds) between two GC cycles
2867 when using ZGC. By default, this option is set to 0 (disabled).
2868 -XX:ZFragmentationLimit=percent
2870 Sets the maximum acceptable heap fragmentation (in percent) for
2871 ZGC. By default, this option is set to 25. Using a lower value
2872 will cause the heap to be compacted more aggressively, to re‐
2873 claim more memory at the cost of using more CPU time.
2874 -XX:+ZProactive
2876 Enables proactive GC cycles when using ZGC. By default, this
2877 option is enabled. ZGC will start a proactive GC cycle if doing
2878 so is expected to have minimal impact on the running applica‐
2879 tion. This is useful if the application is mostly idle or allo‐
2880 cates very few objects, but you still want to keep the heap size
2881 down and allow reference processing to happen even when there
2882 are a lot of free space on the heap.
2883 -XX:+ZUncommit
2885 Enables uncommitting of unused heap memory when using ZGC. By
2886 default, this option is enabled. Uncommitting unused heap memo‐
2887 ry will lower the memory footprint of the JVM, and make that
2888 memory available for other processes to use.
2889 -XX:ZUncommitDelay=seconds
2891 Sets the amount of time (in seconds) that heap memory must have
2892 been unused before being uncommitted. By default, this option
2893 is set to 300 (5 minutes). Committing and uncommitting memory
2894 are relatively expensive operations. Using a lower value will
2895 cause heap memory to be uncommitted earlier, at the risk of soon
2896 having to commit it again.
2897
2899 These java options are deprecated and might be removed in a future JDK
2900 release. They're still accepted and acted upon, but a warning is is‐
2901 sued when they're used.
2902 -Xfuture
2904 Enables strict class-file format checks that enforce close con‐
2905 formance to the class-file format specification. Developers
2906 should use this flag when developing new code. Stricter checks
2907 may become the default in future releases.
2908 -Xloggc:filename
2910 Sets the file to which verbose GC events information should be
2911 redirected for logging. The -Xloggc option overrides -ver‐
2912 bose:gc if both are given with the same java command. -Xlog‐
2913 gc:filename is replaced by -Xlog:gc:filename. See Enable Log‐
2914 ging with the JVM Unified Logging Framework.
2915 Example:
2917 -Xlog:gc:garbage-collection.log
2919 -XX:+FlightRecorder
2921 Enables the use of Java Flight Recorder (JFR) during the runtime
2922 of the application. Since JDK 8u40 this option has not been re‐
2923 quired to use JFR.
2924 -XX:InitialRAMFraction=ratio
2926 Sets the initial amount of memory that the JVM may use for the
2927 Java heap before applying ergonomics heuristics as a ratio of
2928 the maximum amount determined as described in the -XX:MaxRAM op‐
2929 tion. The default value is 64.
2930 Use the option -XX:InitialRAMPercentage instead.
2932 -XX:MaxRAMFraction=ratio
2934 Sets the maximum amount of memory that the JVM may use for the
2935 Java heap before applying ergonomics heuristics as a fraction of
2936 the maximum amount determined as described in the -XX:MaxRAM op‐
2937 tion. The default value is 4.
2938 Specifying this option disables automatic use of compressed oops
2940 if the combined result of this and other options influencing the
2941 maximum amount of memory is larger than the range of memory ad‐
2942 dressable by compressed oops. See -XX:UseCompressedOops for
2943 further information about compressed oops.
2944 Use the option -XX:MaxRAMPercentage instead.
2946 -XX:MinRAMFraction=ratio
2948 Sets the maximum amount of memory that the JVM may use for the
2949 Java heap before applying ergonomics heuristics as a fraction of
2950 the maximum amount determined as described in the -XX:MaxRAM op‐
2951 tion for small heaps. A small heap is a heap of approximately
2952 125 MB. The default value is 2.
2953 Use the option -XX:MinRAMPercentage instead.
2955 -XX:+UseBiasedLocking
2957 Enables the use of biased locking. Some applications with sig‐
2958 nificant amounts of uncontended synchronization may attain sig‐
2959 nificant speedups with this flag enabled, but applications with
2960 certain patterns of locking may see slowdowns.
2961 By default, this option is disabled.
2963
2965 These java options are still accepted but ignored, and a warning is is‐
2966 sued when they're used.
2967 --illegal-access=parameter
2969 Controlled relaxed strong encapsulation, as defined in JEP 261
2970 [https://openjdk.java.net/jeps/261#Relaxed-strong-encapsula‐
2971 tion]. This option was deprecated in JDK 16 by JEP 396
2972 [https://openjdk.java.net/jeps/396] and made obsolete in JDK 17
2973 by JEP 403 [https://openjdk.java.net/jeps/403].
2974
2976 These java options have been removed in JDK 17 and using them results
2977 in an error of:
2978 Unrecognized VM option option-name
2980 -XX:+UseMembar
2982 Enabled issuing membars on thread-state transitions. This op‐
2983 tion was disabled by default on all platforms except ARM
2984 servers, where it was enabled.
2985 -XX:MaxPermSize=size
2987 Sets the maximum permanent generation space size (in bytes).
2988 This option was deprecated in JDK 8 and superseded by the
2989 -XX:MaxMetaspaceSize option.
2990 -XX:PermSize=size
2992 Sets the space (in bytes) allocated to the permanent generation
2993 that triggers a garbage collection if it's exceeded. This op‐
2994 tion was deprecated in JDK 8 and superseded by the -XX:Metas‐
2995 paceSize option.
2996 -XX:+TraceClassLoading
2998 Enables tracing of classes as they are loaded. By default, this
2999 option is disabled and classes aren't traced.
3000 The replacement Unified Logging syntax is -Xlog:class+load=lev‐
3002 el. See Enable Logging with the JVM Unified Logging Framework
3003 Use level=info for regular information, or level=debug for addi‐
3005 tional information. In Unified Logging syntax, -verbose:class
3006 equals -Xlog:class+load=info,class+unload=info.
3007 -XX:+TraceClassLoadingPreorder
3009 Enables tracing of all loaded classes in the order in which
3010 they're referenced. By default, this option is disabled and
3011 classes aren't traced.
3012 The replacement Unified Logging syntax is -Xlog:class+pre‐
3014 order=debug. See Enable Logging with the JVM Unified Logging
3015 Framework.
3016 -XX:+TraceClassResolution
3018 Enables tracing of constant pool resolutions. By default, this
3019 option is disabled and constant pool resolutions aren't traced.
3020 The replacement Unified Logging syntax is -Xlog:class+re‐
3022 solve=debug. See Enable Logging with the JVM Unified Logging
3023 Framework.
3024 -XX:+TraceLoaderConstraints
3026 Enables tracing of the loader constraints recording. By de‐
3027 fault, this option is disabled and loader constraints recording
3028 isn't traced.
3029 The replacement Unified Logging syntax is -Xlog:class+load‐
3031 er+constraints=info. See Enable Logging with the JVM Unified
3032 Logging Framework.
3033 For the lists and descriptions of options removed in previous releases
3035 see the Removed Java Options section in:
3036 • Java Platform, Standard Edition Tools Reference, Release 16
3038 [https://docs.oracle.com/en/java/javase/16/docs/specs/man/java.html]
3039 • Java Platform, Standard Edition Tools Reference, Release 15
3041 [https://docs.oracle.com/en/java/javase/15/docs/specs/man/java.html]
3042 • Java Platform, Standard Edition Tools Reference, Release 14
3044 [https://docs.oracle.com/en/java/javase/14/docs/specs/man/java.html]
3045 • Java Platform, Standard Edition Tools Reference, Release 13
3047 [https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html]
3048 • Java Platform, Standard Edition Tools Reference, Release 12
3050 [https://docs.oracle.com/en/java/javase/12/tools/ja‐
3051 va.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE]
3052 • Java Platform, Standard Edition Tools Reference, Release 11
3054 [https://docs.oracle.com/en/java/javase/11/tools/ja‐
3055 va.html#GUID-741FC470-AA3E-494A-8D2B-1B1FE4A990D1]
3056 • Java Platform, Standard Edition Tools Reference, Release 10
3058 [https://docs.oracle.com/javase/10/tools/java.htm#JSWOR624]
3059 • Java Platform, Standard Edition Tools Reference, Release 9
3061 [https://docs.oracle.com/javase/9/tools/java.htm#JSWOR624]
3062 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3064 JDK on Windows [https://docs.oracle.com/javase/8/docs/tech‐
3065 notes/tools/windows/java.html#BGBCIEFC]
3066 • Java Platform, Standard Edition Tools Reference, Release 8 for Oracle
3068 JDK on Solaris, Linux, and macOS [https://docs.ora‐
3069 cle.com/javase/8/docs/technotes/tools/unix/java.html#BGBCIEFC]
3070
3072 You can shorten or simplify the java command by using @ argument files
3073 to specify one or more text files that contain arguments, such as op‐
3074 tions and class names, which are passed to the java command. This
3075 let's you to create java commands of any length on any operating sys‐
3076 tem.
3077 In the command line, use the at sign (@) prefix to identify an argument
3079 file that contains java options and class names. When the java command
3080 encounters a file beginning with the at sign (@), it expands the con‐
3081 tents of that file into an argument list just as they would be speci‐
3082 fied on the command line.
3083 The java launcher expands the argument file contents until it encoun‐
3085 ters the --disable-@files option. You can use the --disable-@files op‐
3086 tion anywhere on the command line, including in an argument file, to
3087 stop @ argument files expansion.
3088 The following items describe the syntax of java argument files:
3090 • The argument file must contain only ASCII characters or characters in
3092 system default encoding that's ASCII friendly, such as UTF-8.
3093 • The argument file size must not exceed MAXINT (2,147,483,647) bytes.
3095 • The launcher doesn't expand wildcards that are present within an ar‐
3097 gument file.
3098 • Use white space or new line characters to separate arguments included
3100 in the file.
3101 • White space includes a white space character, \t, \n, \r, and \f.
3103 For example, it is possible to have a path with a space, such as
3105 c:\Program Files that can be specified as either "c:\\Program Files"
3106 or, to avoid an escape, c:\Program" "Files.
3107 • Any option that contains spaces, such as a path component, must be
3109 within quotation marks using quotation ('"') characters in its en‐
3110 tirety.
3111 • A string within quotation marks may contain the characters \n, \r,
3113 \t, and \f. They are converted to their respective ASCII codes.
3114 • If a file name contains embedded spaces, then put the whole file name
3116 in double quotation marks.
3117 • File names in an argument file are relative to the current directory,
3119 not to the location of the argument file.
3120 • Use the number sign # in the argument file to identify comments. All
3122 characters following the # are ignored until the end of line.
3123 • Additional at sign @ prefixes to @ prefixed options act as an escape,
3125 (the first @ is removed and the rest of the arguments are presented
3126 to the launcher literally).
3127 • Lines may be continued using the continuation character (\) at the
3129 end-of-line. The two lines are concatenated with the leading white
3130 spaces trimmed. To prevent trimming the leading white spaces, a con‐
3131 tinuation character (\) may be placed at the first column.
3132 • Because backslash (\) is an escape character, a backslash character
3134 must be escaped with another backslash character.
3135 • Partial quote is allowed and is closed by an end-of-file.
3137 • An open quote stops at end-of-line unless \ is the last character,
3139 which then joins the next line by removing all leading white space
3140 characters.
3141 • Wildcards (*) aren't allowed in these lists (such as specifying *.ja‐
3143 va).
3144 • Use of the at sign (@) to recursively interpret files isn't support‐
3146 ed.
3147 Example of Open or Partial Quotes in an Argument File
3149 In the argument file,
3150 -cp "lib/
3152 cool/
3153 app/
3154 jars
3155 this is interpreted as:
3157 -cp lib/cool/app/jars
3159 Example of a Backslash Character Escaped with Another Backslash
3161 Character in an Argument File
3162 To output the following:
3164 -cp c:\Program Files (x86)\Java\jre\lib\ext;c:\Program Files\Ja‐
3166 va\jre9\lib\ext
3167 The backslash character must be specified in the argument file as:
3169 -cp "c:\\Program Files (x86)\\Java\\jre\\lib\\ext;c:\\Pro‐
3171 gram Files\\Java\\jre9\\lib\\ext"
3172 Example of an EOL Escape Used to Force Concatenation of Lines in an
3174 Argument File
3175 In the argument file,
3177 -cp "/lib/cool app/jars:\
3179 /lib/another app/jars"
3180 This is interpreted as:
3182 -cp /lib/cool app/jars:/lib/another app/jars
3184 Example of Line Continuation with Leading Spaces in an Argument File
3186 In the argument file,
3187 -cp "/lib/cool\
3189 \app/jars???
3190 This is interpreted as:
3192 -cp /lib/cool app/jars
3194 Examples of Using Single Argument File
3196 You can use a single argument file, such as myargumentfile in the fol‐
3197 lowing example, to hold all required java arguments:
3198 java @myargumentfile
3200 Examples of Using Argument Files with Paths
3202 You can include relative paths in argument files; however, they're rel‐
3203 ative to the current working directory and not to the paths of the ar‐
3204 gument files themselves. In the following example, path1/options and
3205 path2/options represent argument files with different paths. Any rela‐
3206 tive paths that they contain are relative to the current working direc‐
3207 tory and not to the argument files:
3208 java @path1/options @path2/classes
3210
3212 Overview
3213 There are occasions when having insight into the current state of the
3214 JVM code heap would be helpful to answer questions such as:
3215 • Why was the JIT turned off and then on again and again?
3217 • Where has all the code heap space gone?
3219 • Why is the method sweeper not working effectively?
3221 To provide this insight, a code heap state analytics feature has been
3223 implemented that enables on-the-fly analysis of the code heap. The an‐
3224 alytics process is divided into two parts. The first part examines the
3225 entire code heap and aggregates all information that is believed to be
3226 useful or important. The second part consists of several independent
3227 steps that print the collected information with an emphasis on differ‐
3228 ent aspects of the data. Data collection and printing are done on an
3229 "on request" basis.
3230 Syntax
3232 Requests for real-time, on-the-fly analysis can be issued with the fol‐
3233 lowing command:
3234 jcmd pid Compiler.CodeHeap_Analytics [function] [granularity]
3236 If you are only interested in how the code heap looks like after run‐
3238 ning a sample workload, you can use the command line option:
3239 -Xlog:codecache=Trace
3241 To see the code heap state when a "CodeCache full" condition exists,
3243 start the VM with the command line option:
3244 -Xlog:codecache=Debug
3246 See CodeHeap State Analytics (OpenJDK) [https://bugs.openjdk.ja‐
3248 va.net/secure/attachment/75649/JVM_CodeHeap_StateAnalytics_V2.pdf] for
3249 a detailed description of the code heap state analytics feature, the
3250 supported functions, and the granularity options.
3251
3253 You use the -Xlog option to configure or enable logging with the Java
3254 Virtual Machine (JVM) unified logging framework.
3255 Synopsis
3257 -Xlog[:[what][:[output][:[decorators][:output-options[,...]]]]]
3258 -Xlog:directive
3260 what Specifies a combination of tags and levels of the form
3262 tag1[+tag2...][*][=level][,...]. Unless the wildcard (*) is
3263 specified, only log messages tagged with exactly the tags speci‐
3264 fied are matched. See -Xlog Tags and Levels.
3265 output Sets the type of output. Omitting the output type defaults to
3267 stdout. See -Xlog Output.
3268 decorators
3270 Configures the output to use a custom set of decorators. Omit‐
3271 ting decorators defaults to uptime, level, and tags. See Deco‐
3272 rations.
3273 output-options
3275 Sets the -Xlog logging output options.
3276 directive
3278 A global option or subcommand: help, disable, async
3279 Description
3281 The Java Virtual Machine (JVM) unified logging framework provides a
3282 common logging system for all components of the JVM. GC logging for
3283 the JVM has been changed to use the new logging framework. The mapping
3284 of old GC flags to the corresponding new Xlog configuration is de‐
3285 scribed in Convert GC Logging Flags to Xlog. In addition, runtime log‐
3286 ging has also been changed to use the JVM unified logging framework.
3287 The mapping of legacy runtime logging flags to the corresponding new
3288 Xlog configuration is described in Convert Runtime Logging Flags to
3289 Xlog.
3290 The following provides quick reference to the -Xlog command and syntax
3292 for options:
3293 -Xlog Enables JVM logging on an info level.
3295 -Xlog:help
3297 Prints -Xlog usage syntax and available tags, levels, and deco‐
3298 rators along with example command lines with explanations.
3299 -Xlog:disable
3301 Turns off all logging and clears all configuration of the log‐
3302 ging framework including the default configuration for warnings
3303 and errors.
3304 -Xlog[:option]
3306 Applies multiple arguments in the order that they appear on the
3307 command line. Multiple -Xlog arguments for the same output
3308 override each other in their given order.
3309 The option is set as:
3311 [tag-selection][:[output][:[decorators][:output-op‐
3313 tions]]]
3314 Omitting the tag-selection defaults to a tag-set of all and a
3316 level of info.
3317 tag[+...] all
3319 The all tag is a meta tag consisting of all tag-sets available.
3321 The asterisk * in a tag set definition denotes a wildcard tag
3322 match. Matching with a wildcard selects all tag sets that con‐
3323 tain at least the specified tags. Without the wildcard, only
3324 exact matches of the specified tag sets are selected.
3325 output-options is
3327 filecount=file-count filesize=file size with optional K,
3329 M or G suffix
3330 Default Configuration
3332 When the -Xlog option and nothing else is specified on the command
3333 line, the default configuration is used. The default configuration
3334 logs all messages with a level that matches either warning or error re‐
3335 gardless of what tags the message is associated with. The default con‐
3336 figuration is equivalent to entering the following on the command line:
3337 -Xlog:all=warning:stdout:uptime,level,tags
3339 Controlling Logging at Runtime
3341 Logging can also be controlled at run time through Diagnostic Commands
3342 (with the jcmd utility). Everything that can be specified on the com‐
3343 mand line can also be specified dynamically with the VM.log command.
3344 As the diagnostic commands are automatically exposed as MBeans, you can
3345 use JMX to change logging configuration at run time.
3346 -Xlog Tags and Levels
3348 Each log message has a level and a tag set associated with it. The
3349 level of the message corresponds to its details, and the tag set corre‐
3350 sponds to what the message contains or which JVM component it involves
3351 (such as, gc, jit, or os). Mapping GC flags to the Xlog configuration
3352 is described in Convert GC Logging Flags to Xlog. Mapping legacy run‐
3353 time logging flags to the corresponding Xlog configuration is described
3354 in Convert Runtime Logging Flags to Xlog.
3355 Available log levels:
3357 • off
3359 • trace
3361 • debug
3363 • info
3365 • warning
3367 • error
3369 Available log tags:
3371 There are literally dozens of log tags, which in the right combina‐
3373 tions, will enable a range of logging output. The full set of avail‐
3374 able log tags can be seen using -Xlog:help. Specifying all instead of
3375 a tag combination matches all tag combinations.
3376 -Xlog Output
3378 The -Xlog option supports the following types of outputs:
3379 • stdout --- Sends output to stdout
3381 • stderr --- Sends output to stderr
3383 • file=filename --- Sends output to text file(s).
3385 When using file=filename, specifying %p and/or %t in the file name ex‐
3387 pands to the JVM's PID and startup timestamp, respectively. You can
3388 also configure text files to handle file rotation based on file size
3389 and a number of files to rotate. For example, to rotate the log file
3390 every 10 MB and keep 5 files in rotation, specify the options file‐
3391 size=10M, filecount=5. The target size of the files isn't guaranteed
3392 to be exact, it's just an approximate value. Files are rotated by de‐
3393 fault with up to 5 rotated files of target size 20 MB, unless config‐
3394 ured otherwise. Specifying filecount=0 means that the log file
3395 shouldn't be rotated. There's a possibility of the pre-existing log
3396 file getting overwritten.
3397 -Xlog Output Mode
3399 By default logging messages are output synchronously - each log message
3400 is written to the designated output when the logging call is made. But
3401 you can instead use asynchronous logging mode by specifying:
3402 -Xlog:async
3404 Write all logging asynchronously.
3405 In asynchronous logging mode, log sites enqueue all logging messages to
3407 an intermediate buffer and a standalone thread is responsible for
3408 flushing them to the corresponding outputs. The intermediate buffer is
3409 bounded and on buffer exhaustion the enqueuing message is discarded.
3410 Log entry write operations are guaranteed non-blocking.
3411 The option -XX:AsyncLogBufferSize=N specifies the memory budget in
3413 bytes for the intermediate buffer. The default value should be big
3414 enough to cater for most cases. Users can provide a custom value to
3415 trade memory overhead for log accuracy if they need to.
3416 Decorations
3418 Logging messages are decorated with information about the message. You
3419 can configure each output to use a custom set of decorators. The order
3420 of the output is always the same as listed in the table. You can con‐
3421 figure the decorations to be used at run time. Decorations are
3422 prepended to the log message. For example:
3423 [6.567s][info][gc,old] Old collection complete
3425 Omitting decorators defaults to uptime, level, and tags. The none dec‐
3427 orator is special and is used to turn off all decorations.
3428 time (t), utctime (utc), uptime (u), timemillis (tm), uptimemillis
3430 (um), timenanos (tn), uptimenanos (un), hostname (hn), pid (p), tid
3431 (ti), level (l), tags (tg) decorators can also be specified as none for
3432 no decoration.
3433 Decorations Description
3435 ──────────────────────────────────────────────────────────────────────────
3436 time or t Current time and date in ISO-8601 format.
3437 utctime or utc Universal Time Coordinated or Coordinated Universal
3438 Time.
3439 uptime or u Time since the start of the JVM in seconds and mil‐
3440 liseconds. For example, 6.567s.
3441 timemillis or The same value as generated by System.currentTimeMil‐
3442 tm lis()
3443 uptimemillis or Milliseconds since the JVM started.
3444 um
3445 timenanos or tn The same value generated by System.nanoTime().
3446 uptimenanos or Nanoseconds since the JVM started.
3447 un
3448 hostname or hn The host name.
3449 pid or p The process identifier.
3450 tid or ti The thread identifier.
3451 level or l The level associated with the log message.
3452 tags or tg The tag-set associated with the log message.
3453 Convert GC Logging Flags to Xlog
3455 Legacy Garbage Collec‐ Xlog Configura‐ Comment
3456 tion (GC) Flag tion
3457 ───────────────────────────────────────────────────────────────────────────────────────
3458 G1PrintHeapRegions -Xlog:gc+re‐ Not Applicable
3459 gion=trace
3460 GCLogFileSize No configuration Log rotation is handled by the
3461 available framework.
3462 NumberOfGCLogFiles Not Applicable Log rotation is handled by the
3463 framework.
3464 PrintAdaptiveSizePoli‐ -Xlog:gc+er‐ Use a level of debug for most
3465 cy go*=level of the information, or a level
3466 of trace for all of what was
3467 logged for PrintAdaptive‐
3468 SizePolicy.
3469 PrintGC -Xlog:gc Not Applicable
3470 PrintGCApplicationCon‐ -Xlog:safepoint Note that PrintGCApplication‐
3471 currentTime ConcurrentTime and PrintGCAp‐
3472 plicationStoppedTime are logged
3473 on the same tag and aren't sep‐
3474 arated in the new logging.
3475 PrintGCApplication‐ -Xlog:safepoint Note that PrintGCApplication‐
3476 StoppedTime ConcurrentTime and PrintGCAp‐
3477 plicationStoppedTime are logged
3478 on the same tag and not sepa‐
3479 rated in the new logging.
3480 PrintGCCause Not Applicable GC cause is now always logged.
3481 PrintGCDateStamps Not Applicable Date stamps are logged by the
3482 framework.
3483 PrintGCDetails -Xlog:gc* Not Applicable
3484 PrintGCID Not Applicable GC ID is now always logged.
3485 PrintGCTaskTimeStamps -Xlog:gc+task*=de‐ Not Applicable
3486 bug
3487 PrintGCTimeStamps Not Applicable Time stamps are logged by the
3488 framework.
3489 PrintHeapAtGC -Xlog:gc+heap=trace Not Applicable
3491 PrintReferenceGC -Xlog:gc+ref*=debug Note that in the old logging,
3492 PrintReferenceGC had an effect
3493 only if PrintGCDetails was also
3494 enabled.
3495 PrintStringDeduplica‐ `-Xlog:gc+stringdedup*=de‐ ` Not Applicable
3496 tionStatistics bug
3497 PrintTenuringDistribu‐ -Xlog:gc+age*=level Use a level of debug for the
3498 tion most relevant information, or a
3499 level of trace for all of what
3500 was logged for PrintTenur‐
3501 ingDistribution.
3502 UseGCLogFileRotation Not Applicable What was logged for PrintTenur‐
3503 ingDistribution.
3504 Convert Runtime Logging Flags to Xlog
3506 These legacy flags are no longer recognized and will cause an error if
3507 used directly. Use their unified logging equivalent instead.
3508 Legacy Runtime Xlog Configuration Comment
3510 Flag
3511 ──────────────────────────────────────────────────────────────────────────────
3512 TraceExceptions -Xlog:exceptions=in‐ Not Applicable
3513 fo
3514 TraceClassLoad‐ -Xlog:class+load=lev‐ Use level=info for regular informa‐
3515 ing el tion, or level=debug for additional
3516 information. In Unified Logging
3517 syntax, -verbose:class equals
3518 -Xlog:class+load=info,class+un‐
3519 load=info.
3520 TraceClassLoad‐ -Xlog:class+pre‐ Not Applicable
3521 ingPreorder order=debug
3522 TraceClassUn‐ -Xlog:class+un‐ Use level=info for regular informa‐
3523 loading load=level tion, or level=trace for additional
3524 information. In Unified Logging
3525 syntax, -verbose:class equals
3526 -Xlog:class+load=info,class+un‐
3527 load=info.
3528 VerboseVerifi‐ -Xlog:verifica‐ Not Applicable
3529 cation tion=info
3530 TraceClassPaths -Xlog:class+path=info Not Applicable
3531 TraceClassReso‐ -Xlog:class+re‐ Not Applicable
3532 lution solve=debug
3533 TraceClassIni‐ -Xlog:class+init=info Not Applicable
3534 tialization
3535 TraceLoaderCon‐ -Xlog:class+load‐ Not Applicable
3536 straints er+constraints=info
3537 TraceClassLoad‐ -Xlog:class+load‐ Use level=debug for regular infor‐
3538 erData er+data=level mation or level=trace for addition‐
3539 al information.
3540 TraceSafepoint‐ -Xlog:safe‐ Not Applicable
3541 CleanupTime point+cleanup=info
3542 TraceSafepoint -Xlog:safepoint=debug Not Applicable
3543 TraceMonitorIn‐ -Xlog:monitorinfla‐ Not Applicable
3544 flation tion=debug
3545 TraceBiased‐ -Xlog:biasedlock‐ Use level=info for regular informa‐
3546 Locking ing=level tion, or level=trace for additional
3547 information.
3548 TraceRede‐ -Xlog:rede‐ level=info, debug, and trace pro‐
3549 fineClasses fine+class*=level vide increasing amounts of informa‐
3550 tion.
3551 -Xlog Usage Examples
3553 The following are -Xlog examples.
3554 -Xlog Logs all messages by using the info level to stdout with uptime,
3556 levels, and tags decorations. This is equivalent to using:
3557 -Xlog:all=info:stdout:uptime,levels,tags
3559 -Xlog:gc
3561 Logs messages tagged with the gc tag using info level to stdout.
3562 The default configuration for all other messages at level warn‐
3563 ing is in effect.
3564 -Xlog:gc,safepoint
3566 Logs messages tagged either with the gc or safepoint tags, both
3567 using the info level, to stdout, with default decorations. Mes‐
3568 sages tagged with both gc and safepoint won't be logged.
3569 -Xlog:gc+ref=debug
3571 Logs messages tagged with both gc and ref tags, using the debug
3572 level to stdout, with default decorations. Messages tagged only
3573 with one of the two tags won't be logged.
3574 -Xlog:gc=debug:file=gc.txt:none
3576 Logs messages tagged with the gc tag using the debug level to a
3577 file called gc.txt with no decorations. The default configura‐
3578 tion for all other messages at level warning is still in effect.
3579 -Xlog:gc=trace:file=gctrace.txt:uptimemillis,pids:filecount=5,file‐
3581 size=1024
3582 Logs messages tagged with the gc tag using the trace level to a
3583 rotating file set with 5 files with size 1 MB with the base name
3584 gctrace.txt and uses decorations uptimemillis and pid.
3585 The default configuration for all other messages at level warn‐
3587 ing is still in effect.
3588 -Xlog:gc::uptime,tid
3590 Logs messages tagged with the gc tag using the default 'info'
3591 level to default the output stdout and uses decorations uptime
3592 and tid. The default configuration for all other messages at
3593 level warning is still in effect.
3594 -Xlog:gc*=info,safepoint*=off
3596 Logs messages tagged with at least gc using the info level, but
3597 turns off logging of messages tagged with safepoint. Messages
3598 tagged with both gc and safepoint won't be logged.
3599 -Xlog:disable -Xlog:safepoint=trace:safepointtrace.txt
3601 Turns off all logging, including warnings and errors, and then
3602 enables messages tagged with safepointusing tracelevel to the
3603 file safepointtrace.txt. The default configuration doesn't ap‐
3604 ply, because the command line started with -Xlog:disable.
3605 Complex -Xlog Usage Examples
3607 The following describes a few complex examples of using the -Xlog op‐
3608 tion.
3609 -Xlog:gc+class*=debug
3611 Logs messages tagged with at least gc and class tags using the
3612 debug level to stdout. The default configuration for all other
3613 messages at the level warning is still in effect
3614 -Xlog:gc+meta*=trace,class*=off:file=gcmetatrace.txt
3616 Logs messages tagged with at least the gc and meta tags using
3617 the trace level to the file metatrace.txt but turns off all mes‐
3618 sages tagged with class. Messages tagged with gc, meta, and
3619 class aren't be logged as class* is set to off. The default
3620 configuration for all other messages at level warning is in ef‐
3621 fect except for those that include class.
3622 -Xlog:gc+meta=trace
3624 Logs messages tagged with exactly the gc and meta tags using the
3625 trace level to stdout. The default configuration for all other
3626 messages at level warning is still be in effect.
3627 -Xlog:gc+class+heap*=debug,meta*=warning,threads*=off
3629 Logs messages tagged with at least gc, class, and heap tags us‐
3630 ing the trace level to stdout but only log messages tagged with
3631 meta with level. The default configuration for all other mes‐
3632 sages at the level warning is in effect except for those that
3633 include threads.
3634
3636 You use values provided to all Java Virtual Machine (JVM) command-line
3637 flags for validation and, if the input value is invalid or
3638 out-of-range, then an appropriate error message is displayed.
3639 Whether they're set ergonomically, in a command line, by an input tool,
3641 or through the APIs (for example, classes contained in the package ja‐
3642 va.lang.management) the values provided to all Java Virtual Machine
3643 (JVM) command-line flags are validated. Ergonomics are described in
3644 Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collec‐
3645 tion Tuning Guide.
3646 Range and constraints are validated either when all flags have their
3648 values set during JVM initialization or a flag's value is changed dur‐
3649 ing runtime (for example using the jcmd tool). The JVM is terminated
3650 if a value violates either the range or constraint check and an appro‐
3651 priate error message is printed on the error stream.
3652 For example, if a flag violates a range or a constraint check, then the
3654 JVM exits with an error:
3655 java -XX:AllocatePrefetchStyle=5 -version
3657 intx AllocatePrefetchStyle=5 is outside the allowed range [ 0 ... 3 ]
3658 Improperly specified VM option 'AllocatePrefetchStyle=5'
3659 Error: Could not create the Java Virtual Machine.
3660 Error: A fatal exception has occurred. Program will exit.
3661 The flag -XX:+PrintFlagsRanges prints the range of all the flags. This
3663 flag allows automatic testing of the flags by the values provided by
3664 the ranges. For the flags that have the ranges specified, the type,
3665 name, and the actual range is printed in the output.
3666 For example,
3668 intx ThreadStackSize [ 0 ... 9007199254740987 ] {pd product}
3670 For the flags that don't have the range specified, the values aren't
3672 displayed in the print out. For example:
3673 size_t NewSize [ ... ] {product}
3675 This helps to identify the flags that need to be implemented. The au‐
3677 tomatic testing framework can skip those flags that don't have values
3678 and aren't implemented.
3679
3681 You use large pages, also known as huge pages, as memory pages that are
3682 significantly larger than the standard memory page size (which varies
3683 depending on the processor and operating system). Large pages optimize
3684 processor Translation-Lookaside Buffers.
3685 A Translation-Lookaside Buffer (TLB) is a page translation cache that
3687 holds the most-recently used virtual-to-physical address translations.
3688 A TLB is a scarce system resource. A TLB miss can be costly because
3689 the processor must then read from the hierarchical page table, which
3690 may require multiple memory accesses. By using a larger memory page
3691 size, a single TLB entry can represent a larger memory range. This re‐
3692 sults in less pressure on a TLB, and memory-intensive applications may
3693 have better performance.
3694 However, using large pages can negatively affect system performance.
3696 For example, when a large amount of memory is pinned by an application,
3697 it may create a shortage of regular memory and cause excessive paging
3698 in other applications and slow down the entire system. Also, a system
3699 that has been up for a long time could produce excessive fragmentation,
3700 which could make it impossible to reserve enough large page memory.
3701 When this happens, either the OS or JVM reverts to using regular pages.
3702 Linux and Windows support large pages.
3704 Large Pages Support for Linux
3706 Linux supports large pages since version 2.6. To check if your envi‐
3707 ronment supports large pages, try the following:
3708 # cat /proc/meminfo | grep Huge
3710 HugePages_Total: 0
3711 HugePages_Free: 0
3712 ...
3713 Hugepagesize: 2048 kB
3714 If the output contains items prefixed with "Huge", then your system
3716 supports large pages. The values may vary depending on environment.
3717 The Hugepagesize field shows the default large page size in your envi‐
3718 ronment, and the other fields show details for large pages of this
3719 size. Newer kernels have support for multiple large page sizes. To
3720 list the supported page sizes, run this:
3721 # ls /sys/kernel/mm/hugepages/
3723 hugepages-1048576kB hugepages-2048kB
3724 The above environment supports 2 MB and 1 GB large pages, but they need
3726 to be configured so that the JVM can use them. When using large pages
3727 and not enabling transparent huge pages (option -XX:+UseTransparen‐
3728 tHugePages), the number of large pages must be pre-allocated. For ex‐
3729 ample, to enable 8 GB of memory to be backed by 2 MB large pages, login
3730 as root and run:
3731 # echo 4096 > /sys/ker‐
3733 nel/mm/hugepages/hugepages-2048kB/nr_hugepages
3734 It is always recommended to check the value of nr_hugepages after the
3736 request to make sure the kernel was able to allocate the requested num‐
3737 ber of large pages.
3738 When using the option -XX:+UseSHM to enable large pages you also need
3740 to make sure the SHMMAX parameter is configured to allow large enough
3741 shared memory segments to be allocated. To allow a maximum shared seg‐
3742 ment of 8 GB, login as root and run:
3743 # echo 8589934592 > /proc/sys/kernel/shmmax
3745 In some environments this is not needed since the default value is
3747 large enough, but it is important to make sure the value is large
3748 enough to fit the amount of memory intended to be backed by large
3749 pages.
3750 Note: The values contained in /proc and /sys reset after you re‐
3752 boot your system, so may want to set them in an initialization
3753 script (for example, rc.local or sysctl.conf).
3754 If you configure the OS kernel parameters to enable use of large pages,
3756 the Java processes may allocate large pages for the Java heap as well
3757 as other internal areas, for example:
3758 • Code cache
3760 • Marking bitmaps
3762 Consequently, if you configure the nr_hugepages parameter to the size
3764 of the Java heap, then the JVM can still fail to allocate the heap us‐
3765 ing large pages because other areas such as the code cache might al‐
3766 ready have used some of the configured large pages.
3767 Large Pages Support for Windows
3769 To use large pages support on Windows, the administrator must first as‐
3770 sign additional privileges to the user who is running the application:
3771 1. Select Control Panel, Administrative Tools, and then Local Security
3773 Policy.
3774 2. Select Local Policies and then User Rights Assignment.
3776 3. Double-click Lock pages in memory, then add users and/or groups.
3778 4. Reboot your system.
3780 Note that these steps are required even if it's the administrator who's
3782 running the application, because administrators by default don't have
3783 the privilege to lock pages in memory.
3784
3786 Application Class Data Sharing (AppCDS) stores classes used by your ap‐
3787 plications in an archive file. Since these classes are stored in a
3788 format that can be loaded very quickly (compared to classes stored in a
3789 JAR file), AppCDS can improve the start-up time of your applications.
3790 In addition, AppCDS can reduce the runtime memory footprint by sharing
3791 parts of these classes across multiple processes.
3792 Classes in the CDS archive are stored in an optimized format that's
3794 about 2 to 5 times larger than classes stored in JAR files or the JDK
3795 runtime image. Therefore, it's a good idea to archive only those
3796 classes that are actually used by your application. These usually are
3797 just a small portion of all available classes. For example, your ap‐
3798 plication may use only a few APIs provided by a large library.
3799 Using CDS Archives
3801 By default, in most JDK distributions, unless -Xshare:off is specified,
3802 the JVM starts up with a default CDS archive, which is usually located
3803 in JAVA_HOME/lib/server/classes.jsa (or JAVA_HOME\bin\server\class‐
3804 es.jsa on Windows). This archive contains about 1300 core library
3805 classes that are used by most applications.
3806 To use CDS for the exact set of classes used by your application, you
3808 can use the -XX:SharedArchiveFile option, which has the general form:
3809 -XX:SharedArchiveFile=<static_archive>:<dynamic_archive>
3811 • The <static_archive> overrides the default CDS archive.
3813 • The <dynamic_archive> provides additional classes that can be loaded
3815 on top of those in the <static_archive>.
3816 • On Windows, the above path delimiter : should be replaced with ;
3818 (The names "static" and "dyanmic" are used for historical reasons. The
3820 only significance is that the "static" archive is loaded first and the
3821 "dynamic" archive is loaded second).
3822 The JVM can use up to two archives. To use only a single <static_ar‐
3824 chive>, you can omit the <dynamic_archive> portion:
3825 -XX:SharedArchiveFile=<static_archive>
3827 For convenience, the <dynamic_archive> records the location of the
3829 <static_archive>. Therefore, you can omit the <static_archive> by say‐
3830 ing only:
3831 -XX:SharedArchiveFile=<dynamic_archive>
3833 Creating CDS Archives
3835 CDS archives can be created with several methods:
3836 • -Xshare:dump
3838 • -XX:ArchiveClassesAtExit
3840 • jcmd VM.cds
3842 One common operation in all these methods is a "trial run", where you
3844 run the application once to determine the classes that should be stored
3845 in the archive.
3846 Creating a Static CDS Archive File with -Xshare:dump
3848 The following steps create a static CDS archive file that contains all
3849 the classes used by the test.Hello application.
3850 1. Create a list of all classes used by the test.Hello application.
3852 The following command creates a file named hello.classlist that con‐
3853 tains a list of all classes used by this application:
3854 java -Xshare:off -XX:DumpLoadedClassList=hel‐
3856 lo.classlist -cp hello.jar test.Hello
3857 The classpath specified by the -cp parameter must contain only JAR
3859 files.
3860 2. Create a static archive, named hello.jsa, that contains all the
3862 classes in hello.classlist:
3863 java -Xshare:dump -XX:SharedArchiveFile=hel‐
3865 lo.jsa -XX:SharedClassListFile=hello.classlist -cp hello.jar
3866 3. Run the application test.Hello with the archive hello.jsa:
3868 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3870 lo
3871 4. Optional Verify that the test.Hello application is using the class
3873 contained in the hello.jsa shared archive:
3874 java -XX:SharedArchiveFile=hello.jsa -cp hel‐
3876 lo.jar -Xlog:class+load test.Hello
3877 The output of this command should contain the following text:
3879 [info][class,load] test.Hello source: shared objects file
3881 Creating a Dynamic CDS Archive File with -XX:SharedArchiveFile
3883 Advantages of dynamic CDS archives are:
3884 • They usually use less disk space, since they don't need to store the
3886 classes that are already in the static archive.
3887 • They are created with one fewer step than the comparable static ar‐
3889 chive.
3890 The following steps create a dynamic CDS archive file that contains the
3892 classes that are used by the test.Hello application, excluding those
3893 that are already in the default CDS archive.
3894 1. Create a dynamic CDS archive, named hello.jsa, that contains all the
3896 classes in hello.jar loaded by the application test.Hello:
3897 java -XX:ArchiveClassesAtExit=hello.jsa -cp hello.jar Hello
3899 2. Run the application test.Hello with the shared archive hello.jsa:
3901 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar test.Hel‐
3903 lo
3904 3. Optional Repeat step 4 of the previous section to verify that the
3906 test.Hello application is using the class contained in the hello.jsa
3907 shared archive.
3908 It's also possible to create a dynamic CDS archive with a non-default
3910 static CDS archive. E.g.,
3911 java -XX:SharedArchiveFile=base.jsa -XX:ArchiveClassesAtEx‐
3913 it=hello.jsa -cp hello.jar Hello
3914 To run the application using this dynamic CDS archive:
3916 java -XX:SharedArchiveFile=base.jsa:hello.jsa -cp hello.jar Hel‐
3918 lo
3919 (On Windows, the above path delimiter : should be replaced with ;)
3921 As mention above, the name of the static archive can be skipped:
3923 java -XX:SharedArchiveFile=hello.jsa -cp hello.jar Hello
3925 Creating CDS Archive Files with jcmd
3927 The previous two sections require you to modify the application's
3928 start-up script in order to create a CDS archive. Sometimes this could
3929 be difficult, for example, if the application's class path is set up by
3930 complex routines.
3931 The jcmd VM.cds command provides a less intrusive way for creating a
3933 CDS archive by connecting to a running JVM process. You can create ei‐
3934 ther a static:
3935 jcmd <pid> VM.cds static_dump my_static_archive.jsa
3937 or a dynamic archive:
3939 jcmd <pid> VM.cds dynamic_dump my_dynamic_archive.jsa
3941 To use the resulting archive file in a subsequent run of the applica‐
3943 tion without modifying the application's start-up script, you can use
3944 the following technique:
3945 env JAVA_TOOL_OPTIONS=-XX:SharedArchiveFile=my_static_ar‐
3947 chive.jsa bash app_start.sh
3948 Note: to use jcmd <pid> VM.cds dynamic_dump, the JVM process identified
3950 by <pid> must be started with -XX:+RecordDynamicDumpInfo, which can al‐
3951 so be passed to the application start-up script with the same tech‐
3952 nique:
3953 env JAVA_TOOL_OPTIONS=-XX:+RecordDynamicDumpIn‐
3955 fo bash app_start.sh
3956 Restrictions on Class Path and Module Path
3958 • Neither the class path (-classpath and -Xbootclasspath/a) nor the
3959 module path (--module-path) can contain non-empty directories.
3960 • Only modular JAR files are supported in --module-path. Exploded mod‐
3962 ules are not supported.
3963 • The class path used at archive creation time must be the same as (or
3965 a prefix of) the class path used at run time. (There's no such re‐
3966 quirement for the module path.)
3967 • The CDS archive cannot be loaded if any JAR files in the class path
3969 or module path are modified after the archive is generated.
3970 • If any of the VM options --upgrade-module-path, --patch-module or
3972 --limit-modules are specified, CDS is disabled. This means that the
3973 JVM will execute without loading any CDS archives. In addition, if
3974 you try to create a CDS archive with any of these 3 options speci‐
3975 fied, the JVM will report an error.
3976
3978 You can use the Java advanced runtime options to optimize the perfor‐
3979 mance of your applications.
3980 Tuning for Higher Throughput
3982 Use the following commands and advanced options to achieve higher
3983 throughput performance for your application:
3984 java -server -XX:+UseParallelGC -XX:+Use‐
3986 LargePages -Xmn10g -Xms26g -Xmx26g
3987 Tuning for Lower Response Time
3989 Use the following commands and advanced options to achieve lower re‐
3990 sponse times for your application:
3991 java -XX:+UseG1GC -XX:MaxGCPauseMillis=100
3993 Keeping the Java Heap Small and Reducing the Dynamic Footprint of
3995 Embedded Applications
3996 Use the following advanced runtime options to keep the Java heap small
3998 and reduce the dynamic footprint of embedded applications:
3999 -XX:MaxHeapFreeRatio=10 -XX:MinHeapFreeRatio=5
4001 Note: The defaults for these two options are 70% and 40% respec‐
4003 tively. Because performance sacrifices can occur when using
4004 these small settings, you should optimize for a small footprint
4005 by reducing these settings as much as possible without introduc‐
4006 ing unacceptable performance degradation.
4007
4009 The following exit values are typically returned by the launcher when
4010 the launcher is called with the wrong arguments, serious errors, or ex‐
4011 ceptions thrown by the JVM. However, a Java application may choose to
4012 return any value by using the API call System.exit(exitValue). The
4013 values are:
4014 • 0: Successful completion
4016 • >0: An error occurred
4018JDK 17 2021 JAVA(1)