From f6af2e83e078e72ad741ddc8f055d985f7249f47 Mon Sep 17 00:00:00 2001 From: David Holmes Date: Tue, 17 Dec 2024 21:15:36 -0500 Subject: [PATCH 1/3] 8346477: Clarify the Java manpage in relation to the JVM's OnOutOfMemoryError flags --- src/java.base/share/man/java.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/java.base/share/man/java.md b/src/java.base/share/man/java.md index 0beb5bf935c64..c959f39ec9b5f 100644 --- a/src/java.base/share/man/java.md +++ b/src/java.base/share/man/java.md @@ -1292,10 +1292,13 @@ These `java` options control the runtime behavior of the Java HotSpot VM. `-XX:OnOutOfMemoryError=`*string* : Sets a custom command or a series of semicolon-separated commands to run - when an `OutOfMemoryError` exception is first thrown. If the string + when an `OutOfMemoryError` exception is first thrown by the JVM. + If the string contains spaces, then it must be enclosed in quotation marks. For an example of a command string, see the description of the `-XX:OnError` option. + This does not apply to any `OutOfMemoryError` thrown by Java, or native, + code in the JDK libraries. `-XX:+PrintCommandLineFlags` : Enables printing of ergonomically selected JVM flags that appeared on the @@ -2189,10 +2192,12 @@ perform extensive debugging. `-XX:+HeapDumpOnOutOfMemoryError` : Enables the dumping of the Java heap to a file in the current directory by using the heap profiler (HPROF) when a `java.lang.OutOfMemoryError` - exception is thrown. You can explicitly set the heap dump file path and + exception is thrown by the JVM. You can explicitly set the heap dump file path and name using the `-XX:HeapDumpPath` option. By default, this option is disabled and the heap isn't dumped when an `OutOfMemoryError` exception is thrown. + This does not apply to any `OutOfMemoryError` thrown by Java, or native, + code in the JDK libraries. `-XX:HeapDumpPath=`*path* : Sets the path and file name for writing the heap dump provided by the heap From 3c1248379a47096acddaf38608c6323afa86ee46 Mon Sep 17 00:00:00 2001 From: David Holmes Date: Thu, 19 Dec 2024 16:20:40 -0500 Subject: [PATCH 2/3] Refine message based on Thomas's suggestions --- src/java.base/share/man/java.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/java.base/share/man/java.md b/src/java.base/share/man/java.md index c959f39ec9b5f..86f50d644f9a0 100644 --- a/src/java.base/share/man/java.md +++ b/src/java.base/share/man/java.md @@ -1297,6 +1297,11 @@ These `java` options control the runtime behavior of the Java HotSpot VM. contains spaces, then it must be enclosed in quotation marks. For an example of a command string, see the description of the `-XX:OnError` option. + This applies only to `OutOfMemoryError` exceptions caused by Java Heap + exhaustion; it does not apply to `OutOfMemoryError` exceptions thrown + directly from Java code, nor by the JVM for other types of resource + exhaustion (such as native thread creation errors). + This does not apply to any `OutOfMemoryError` thrown by Java, or native, code in the JDK libraries. @@ -2196,8 +2201,10 @@ perform extensive debugging. name using the `-XX:HeapDumpPath` option. By default, this option is disabled and the heap isn't dumped when an `OutOfMemoryError` exception is thrown. - This does not apply to any `OutOfMemoryError` thrown by Java, or native, - code in the JDK libraries. + This applies only to `OutOfMemoryError` exceptions caused by Java Heap + exhaustion; it does not apply to `OutOfMemoryError` exceptions thrown + directly from Java code, nor by the JVM for other types of resource + exhaustion (such as native thread creation errors). `-XX:HeapDumpPath=`*path* : Sets the path and file name for writing the heap dump provided by the heap From 9a9641736b9d39470e2d43a72368c4d27ec7c084 Mon Sep 17 00:00:00 2001 From: David Holmes Date: Sun, 22 Dec 2024 15:49:47 -0500 Subject: [PATCH 3/3] Remove leftover sentence. --- src/java.base/share/man/java.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/java.base/share/man/java.md b/src/java.base/share/man/java.md index 86f50d644f9a0..01f7b3f7e7768 100644 --- a/src/java.base/share/man/java.md +++ b/src/java.base/share/man/java.md @@ -1302,9 +1302,6 @@ These `java` options control the runtime behavior of the Java HotSpot VM. directly from Java code, nor by the JVM for other types of resource exhaustion (such as native thread creation errors). - This does not apply to any `OutOfMemoryError` thrown by Java, or native, - code in the JDK libraries. - `-XX:+PrintCommandLineFlags` : Enables printing of ergonomically selected JVM flags that appeared on the command line. It can be useful to know the ergonomic values set by the JVM,