JDK-8276265 : jcmd man page is outdated
  • Type: Bug
  • Component: hotspot
  • Sub-Component: svc
  • Affected Version: 18
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2021-11-02
  • Updated: 2024-01-16
  • Resolved: 2021-11-11
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 18
18 b24Fixed
Related Reports
Relates :  
JDK-8268893 - jcmd to trim the glibc heap
Relates :  
JDK-8203682 - Add jcmd "VM.classloaders" command to print out class loader hierarchy, details
Relates :  
JDK-8276982 - VM.class_hierarchy jcmd help output and man page text needs clarifications/improvements
Description
jcmd man page is outdated:

Missing from man page:
- Compiler.perfmap
- System.trim_native_heap
- VM.cds
- VM.classloaders
- VM.events
- VM.metaspace

Documentation in man page outdated:
- GC.class_histogram  (-parallel missing)
- GC.heap_dump
- JFR.check, JFR.configure, JFR.dump, JFR.start, JFR.stop all differ in text (e.g. examples missing from man page)
- ManagementAgent.start - man page mentiones "jmxremote.ssl.enabled.cipher.suite" (note singular) which I cannot find in help text
- Thread.print (misses -e)

Sorting in man page not alphabetical.
Comments
Changeset: 3445e50b Author: David Holmes <dholmes@openjdk.org> Date: 2021-11-11 22:10:18 +0000 URL: https://git.openjdk.java.net/jdk/commit/3445e50bd573857660908a964886f94714315f4c
11-11-2021
Summary of changes: New Commands: Compiler.perfmap System.trim_native_heap VM.cds VM.classloaders VM.events VM.metaspace Missing flags: GC.class_histogram -parallel GC.heap_dump - gz and overwrite options Thread.print -e There are further improvements that could be made, some mentioned above. I also noticed a general confusion between arguments and options with some subcommands, but I did not try to address that.
10-11-2021
Thanks Thomas I've taken over the bug to add the new information.
02-11-2021
Hi David, I looked closer and identified a number of commands outdated or outright missing from the manpage. I don't think making a bug for each of them is effective, so I changed the Issue. I prepared a text document for you which contains all the information which need to be added. I did not want a fully automated process, just a help for the occasional maintainer. E.g. the maintainer could call "jcmd -allall" and get a list of all commands, diff that manually against the current man page sources (as I just did) and update those. Wrt to man page vs help texts different: I disagree for practical and usability reasons. I think both should be identical. In practice, where the man page contains content today, it seems to be copied verbatim from the jcmd help text, so this seems to be an established practice. In fact, the help texts are sometimes more verbose than the man page (e.g. wrt JFR options).
02-11-2021
I don't think one-size-fits-all help text is right. The text from `jcmd help` is likely much briefer than what you would expect from a manpage or other online document IMO. And isolating the help text to an external file that can be processed by other doc tools is a far bigger effort than what I had envisaged here.
02-11-2021
Hi David, How about this. AFAICT the man page contains the command descriptions pretty much verbatim. We could generate the man page sources (or the Oracle-internal sources) directly from jcmd help text. Today, jcmd can already print a brief command list using "jcmd help -all". That contains the command name and the one line description text. We could extend that to print all command details (Impact, suboptions etc). The resulting output would be easily digestable by your tools. I think that would be easier than to fix all commands by hand. And after all, we want the command help, command man page and whatever online resources we have to say the same thing, right? p.s. I am very much in favor of good man pages btw. This helps also the downstream Linux distros.
02-11-2021
We have certainly had a problem with people not knowing the jcmd manpage exists and the status of the man pages in general has been somewhat up in the air (and the actual sources (markdown format) remain in the Oracle internal repo with only the nroff formatted versions exported in the OpenJDK repo). But we have been trying to make the manpages more relevant and actively keep the primary set up to date. I think jcmd has suffered from a lack of ownership. If you, [~stuefe], can provide the text I can add it to the markdown source and generate the nroff version. Thanks.
02-11-2021
I can certainly fix this, but are man pages still maintained? I found this: https://bugs.openjdk.java.net/browse/JDK-8207365 which seems to indicate they aren't. At least wrt jcmd, the man page is very outdated. I think nobody is aware this even exists.
02-11-2021