RFR: 8298730: Refactor subsystem_file_line_contents and add docs and tests

[Johan Sjölen]

Hi!

Citing the ticket directly:

The function subsystem_file_line_contents does the simple job of parsing lines in a file, but does so in a fairly complex way. This function can be simplified. The function also has a surprising API, as you need to know that in one case the format string needs to take 2 specifiers, instead of 1. 

Some more context:

`subsystem_file_line_contents` either parses files that look like this:


one_value


Called as: `subsystem_file_line_contents(ctrl, fname, nullptr, "%s")`

Or like this:


key1 val1
key2 val2


Called as:  `subsystem_file_line_contents(ctrl, fname, "key1", "%s %s")`

The API for the key/value case is changed to: `subsystem_file_line_contents(ctrl, fname, "key1", "%s")`. Note: `"%s"`, not `"%s %s"`.

-------------

Commit messages:
 - Freeze stringStream to variable to avoid calling ::base()
 - Document code
 - Change callsites
 - Add tests
 - Check key is at beginning of line, rename file to file_path
 - Do manual substringing of prefix
 - Simplify file name handling and use buf_len constant
 - Split single line and multi line cases into two
 - Use nullptr, not NULL
 - Move buf and discard to usage sites
 - ... and 4 more: https://git.openjdk.org/jdk/compare/86270e30...ce308c66

Changes: https://git.openjdk.org/jdk/pull/11667/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=11667&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8298730
  Stats: 229 lines in 4 files changed: 167 ins; 20 del; 42 mod
  Patch: https://git.openjdk.org/jdk/pull/11667.diff
  Fetch: git fetch https://git.openjdk.org/jdk pull/11667/head:pull/11667

PR: https://git.openjdk.org/jdk/pull/11667