8323546: Cleanup jcmd docs for Compiler.perfmap and VM.cds filename parameter

Reviewed-by: dholmes, sspitsyn, iklam

src/hotspot/share/services/diagnosticCommand.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -851,15 +851,20 @@ void CodeCacheDCmd::execute(DCmdSource source, TRAPS) {
 }
 
 #ifdef LINUX
+#define DEFAULT_PERFMAP_FILENAME "/tmp/perf-<pid>.map"
+
 PerfMapDCmd::PerfMapDCmd(outputStream* output, bool heap) :
              DCmdWithParser(output, heap),
-  _filename("filename", "Name of the map file", "STRING", false)
+  _filename("filename", "Name of the map file", "STRING", false, DEFAULT_PERFMAP_FILENAME)
 {
   _dcmdparser.add_dcmd_argument(&_filename);
 }
 
 void PerfMapDCmd::execute(DCmdSource source, TRAPS) {
-  CodeCache::write_perf_map(_filename.value());
+  // The check for _filename.is_set() is because we don't want to use
+  // DEFAULT_PERFMAP_FILENAME, since it is meant as a description
+  // of the default, not the actual default.
+  CodeCache::write_perf_map(_filename.is_set() ? _filename.value() : nullptr);
 }
 #endif // LINUX
 
@@ -991,10 +996,13 @@ void ClassesDCmd::execute(DCmdSource source, TRAPS) {
 }
 
 #if INCLUDE_CDS
+#define DEFAULT_CDS_ARCHIVE_FILENAME "java_pid<pid>_<subcmd>.jsa"
+
 DumpSharedArchiveDCmd::DumpSharedArchiveDCmd(outputStream* output, bool heap) :
                                      DCmdWithParser(output, heap),
   _suboption("subcmd", "static_dump | dynamic_dump", "STRING", true),
-  _filename("filename", "Name of shared archive to be dumped", "STRING", false)
+  _filename("filename", "Name of shared archive to be dumped", "STRING", false,
+            DEFAULT_CDS_ARCHIVE_FILENAME)
 {
   _dcmdparser.add_dcmd_argument(&_suboption);
   _dcmdparser.add_dcmd_argument(&_filename);
@@ -1003,7 +1011,11 @@ DumpSharedArchiveDCmd::DumpSharedArchiveDCmd(outputStream* output, bool heap) :
 void DumpSharedArchiveDCmd::execute(DCmdSource source, TRAPS) {
   jboolean is_static;
   const char* scmd = _suboption.value();
-  const char* file = _filename.value();
+
+  // The check for _filename.is_set() is because we don't want to use
+  // DEFAULT_CDS_ARCHIVE_FILENAME, since it is meant as a description
+  // of the default, not the actual default.
+  const char* file = _filename.is_set() ? _filename.value() : nullptr;
 
   if (strcmp(scmd, "static_dump") == 0) {
     is_static = JNI_TRUE;

src/jdk.jcmd/share/man/jcmd.1

@@ -254,8 +254,13 @@ Impact: Low
 .PP
 \f[I]arguments\f[R]:
 .IP \[bu] 2
-\f[I]filename\f[R]: (Optional) The name of the map file (STRING, no
+\f[I]filename\f[R]: (Optional) The name of the map file (STRING,
-default value)
+/tmp/perf-<pid>.map)
+.PP
+If \f[V]filename\f[R] is not specified, a default file name is chosen
+using the pid of the target JVM process.
+For example, if the pid is \f[V]12345\f[R], then the default
+\f[V]filename\f[R] will be \f[V]/tmp/perf-12345.map\f[R].
 .RE
 .TP
 \f[V]Compiler.queue\f[R]
@@ -880,7 +885,7 @@ false)
 .PP
 \f[I]arguments\f[R]:
 .IP \[bu] 2
-\f[V]filepath\f[R]: The file path to the output file (STRING, no default
+\f[I]filepath\f[R]: The file path to the output file (STRING, no default
 value)
 .RE
 .TP
@@ -913,11 +918,11 @@ Impact: Medium --- pause time depends on number of loaded classes
 .PP
 \f[I]arguments\f[R]:
 .IP \[bu] 2
-\f[V]subcmd\f[R]: must be either \f[V]static_dump\f[R] or
+\f[I]subcmd\f[R]: must be either \f[V]static_dump\f[R] or
 \f[V]dynamic_dump\f[R] (STRING, no default value)
 .IP \[bu] 2
-\f[V]filename\f[R]: (Optional) Name of the shared archive to be dumped
+\f[I]filename\f[R]: (Optional) Name of the shared archive to be dumped
-(STRING, no default value)
+(STRING, java_pid<pid>_<subcmd>.jsa)
 .PP
 If \f[V]filename\f[R] is not specified, a default file name is chosen
 using the pid of the target JVM process.

test/hotspot/jtreg/serviceability/dcmd/compiler/PerfMapTest.java

@@ -65,7 +65,7 @@ public class PerfMapTest {
         output.stderrShouldBeEmpty();
         output.stdoutShouldBeEmpty();
 
-        Assert.assertTrue(Files.exists(path));
+        Assert.assertTrue(Files.exists(path), "File must exist: " + path);
 
         // Sanity check the file contents
         try {
@@ -94,4 +94,15 @@ public class PerfMapTest {
         } while(Files.exists(path));
         run(new JMXExecutor(), "Compiler.perfmap " + path.toString(), path);
     }
+
+    @Test
+    public void specifiedDefaultMapFile() {
+        // This is a special case of specifiedMapFile() where the filename specified
+        // is the same as the default filename as given in the help output. The dcmd
+        // should treat this literally as the filename and not expand <pid> into
+        // the actual PID of the process.
+        String test_dir = System.getProperty("test.dir", ".");
+        Path path = Paths.get("/tmp/perf-<pid>.map");
+        run(new JMXExecutor(), "Compiler.perfmap " + path.toString(), path);
+    }
 }