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