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